Relay across any mix of links, one online answer for every client, first claim owns a hostname

A tunnel no longer depends on the kind of link under it. The relay hub keeps
one forwarding table per network instead of one per protocol, the envelope
names the end-to-end protocol, and a neighbour reached over several kinds of
transport is sent to over the best open one. A member in the middle needs no
protocol in common with either end. Which protocol a pair runs is settled by
the lower endpoint id's announced order, so both ends agree without asking.
A direct link that comes up later is shorter than the path through others, so
traffic moves to it with the same logical link.

The agent now answers "is it online" once: a live control session or any data
path. Members and peers report how they are reached (direct over a named
transport, relayed through a named member, or no data path yet), and `tsng
status` and the tray both read that instead of a session list and a WireGuard
handshake respectively.

A hostname belongs to whoever claimed it first. A claim carries the time its
author first claimed the name, signed with the record, and replicas order by
(time, id) so every member names the same holder. A later claimant keeps
working by address, is not found by the name, and is told so in its status,
`tsng status`, the tray and a HostnameTaken event.

Wire change: control and data ALPN 5, control PROTOCOL_VERSION 5, envelope
version 2, signing domain v3, state schema 7, local control protocol 18.
Upgrade every member together.

Co-Authored-By: Claude <noreply@anthropic.com>

.cargo/config.toml

@@ -0,0 +1,5 @@
+# Windows: link the C runtime statically, so the agent and the tray start on a
+# machine that has no Visual C++ redistributable installed. The installer ships
+# nothing but our own files and Wintun.
+[target.x86_64-pc-windows-msvc]
+rustflags = ["-C", "target-feature=+crt-static"]

.gitea/workflows/release.yml

@@ -45,7 +45,16 @@ jobs:
             deb: true
             deb_arch: arm64
             pkg_arch: aarch64
-            gnu_target: aarch64-unknown-linux-gnu
+          # 32-bit ARM with hardware float (ARMv7, `v7l`): single-board and edge
+          # devices. Statically linked like the others.
+          - os: ubuntu-latest
+            target: armv7-unknown-linux-musleabihf
+            asset: tsunagi-linux-armv7
+            archive: tar.gz
+            zig: true
+            deb: true
+            deb_arch: armhf
+            pkg_arch: armv7h
           - os: macos-latest
             target: aarch64-apple-darwin
             asset: tsunagi-macos-aarch64
@@ -99,9 +108,9 @@ jobs:
             # one lint to keep the musl build log clean. A real link error still
             # fails the build.
             export RUSTFLAGS="${RUSTFLAGS:-} -A linker_messages"
-            cargo zigbuild --release --locked --target "${{ matrix.target }}" --bin tsunagi
+            cargo zigbuild --release --locked --target "${{ matrix.target }}" --bin tsng
           else
-            cargo build --release --locked --target "${{ matrix.target }}" --bin tsunagi
+            cargo build --release --locked --target "${{ matrix.target }}" --bin tsng
           fi
 
       # The tray GUI. On Linux it is built against glibc (an old baseline for
@@ -111,11 +120,19 @@ jobs:
         shell: bash
         run: |
           set -euo pipefail
-          export RUSTFLAGS="${RUSTFLAGS:-} -A linker_messages"
           if [[ "${{ runner.os }}" == "Linux" ]]; then
-            rustup target add "${{ matrix.gnu_target }}"
+            if [[ -n "${{ matrix.gnu_target }}" ]]; then
-            cargo zigbuild --release --locked \
+              # tray-icon links GTK and libappindicator through pkg-config, which
-              --target "${{ matrix.gnu_target }}.2.28" --bin tsunagi-tray
+              # has no cross story under zig, so the Linux GUI is built natively
+              # (x86_64 only) against the runner's glibc.
+              sudo apt-get update
+              sudo apt-get install -y --no-install-recommends \
+                libgtk-3-dev libayatana-appindicator3-dev libxdo-dev
+              cargo build --release --locked \
+                --target "${{ matrix.gnu_target }}" --bin tsunagi-tray
+            else
+              echo "no GUI build for ${{ matrix.target }}"
+            fi
           else
             cargo build --release --locked --target "${{ matrix.target }}" --bin tsunagi-tray
           fi
@@ -129,15 +146,17 @@ jobs:
           stage="dist/pkg/${{ matrix.asset }}"
           mkdir -p "$stage"
 
-          bin="tsunagi"
+          bin="tsng"
-          [[ "${{ runner.os }}" == "Windows" ]] && bin="tsunagi.exe"
+          [[ "${{ runner.os }}" == "Windows" ]] && bin="tsng.exe"
           cp "target/${{ matrix.target }}/release/${bin}" "$stage/"
 
-          # The tray GUI alongside it: glibc build on Linux, native elsewhere.
+          # The tray GUI alongside it, where it was built (Linux: x86_64 only).
           tray="tsunagi-tray"
           [[ "${{ runner.os }}" == "Windows" ]] && tray="tsunagi-tray.exe"
           if [[ "${{ runner.os }}" == "Linux" ]]; then
-            cp "target/${{ matrix.gnu_target }}/release/${tray}" "$stage/"
+            if [[ -n "${{ matrix.gnu_target }}" ]]; then
+              cp "target/${{ matrix.gnu_target }}/release/${tray}" "$stage/"
+            fi
           else
             cp "target/${{ matrix.target }}/release/${tray}" "$stage/"
           fi
@@ -154,6 +173,10 @@ jobs:
             macOS)
               cp dist/macos/cy.hexor.tsunagi.plist "$stage/"
               cp dist/macos/README.md "$stage/INSTALL.md"
+              # The tray as an application bundle, for the Homebrew cask.
+              bash dist/macos/build-app.sh \
+                "target/${{ matrix.target }}/release/tsunagi-tray" \
+                "$version" "$stage/Tsunagi.app"
               ;;
             Windows)
               cp dist/windows/README.md "$stage/INSTALL.md"
@@ -167,6 +190,29 @@ jobs:
             tar -C dist/pkg -czf "${archive}" "${{ matrix.asset }}"
           fi
 
+      # The Windows installer: the agent as a service, Wintun, the tray and the
+      # PATH entry in one setup program. Wintun is the signed library from
+      # wintun.net, pinned by hash so a changed download fails the build.
+      - name: Build the Windows installer
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = 'Stop'
+          $version = $env:GITHUB_REF_NAME.TrimStart('v')
+          Invoke-WebRequest -Uri https://www.wintun.net/builds/wintun-0.14.1.zip -OutFile wintun.zip
+          $hash = (Get-FileHash wintun.zip -Algorithm SHA256).Hash
+          if ($hash -ne '07C256185D6EE3652E09FA55C0B673E2624B565E02C4B9091C79CA7D2F24EF51') {
+            throw "wintun.zip has an unexpected hash: $hash"
+          }
+          Expand-Archive wintun.zip -DestinationPath wintun-dl
+          choco install innosetup -y --no-progress
+          $iscc = Join-Path ${env:ProgramFiles(x86)} 'Inno Setup 6\ISCC.exe'
+          $stage = Join-Path $PWD 'dist/pkg/${{ matrix.asset }}'
+          & $iscc "/DAppVersion=$version" "/DSourceDir=$stage" `
+            "/DWintunDir=$(Join-Path $PWD 'wintun-dl/wintun/bin/amd64')" `
+            "/O$PWD" dist/windows/tsunagi.iss
+          if ($LASTEXITCODE -ne 0) { throw "ISCC failed with $LASTEXITCODE" }
+
       # A dependency-free .deb for the x86_64 and aarch64 Linux builds: it drops
       # the static binary, the systemd service and the polkit rule. Built with
       # dpkg-deb (present on the runner); see dist/deb/build-deb.sh.
@@ -177,7 +223,7 @@ jobs:
           set -euo pipefail
           version="${GITHUB_REF_NAME#v}"
           bash dist/deb/build-deb.sh \
-            "target/${{ matrix.target }}/release/tsunagi" \
+            "target/${{ matrix.target }}/release/tsng" \
             "${{ matrix.deb_arch }}" \
             "$version" \
             "tsunagi_${version}_${{ matrix.deb_arch }}.deb"
@@ -193,7 +239,7 @@ jobs:
           version="${GITHUB_REF_NAME#v}"
           pkgver="${version//-/_}"
           bash dist/arch/build-pkg.sh \
-            "target/${{ matrix.target }}/release/tsunagi" \
+            "target/${{ matrix.target }}/release/tsng" \
             "${{ matrix.pkg_arch }}" \
             "$version" \
             "tsunagi-${pkgver}-1-${{ matrix.pkg_arch }}.pkg.tar.zst"
@@ -201,7 +247,7 @@ jobs:
       # The GUI variants: the same agent plus the tray binary and a desktop
       # launcher, named tsunagi-gui (conflicting with the headless packages).
       - name: Build the GUI packages
-        if: matrix.deb
+        if: matrix.gnu_target
         shell: bash
         run: |
           set -euo pipefail
@@ -209,11 +255,11 @@ jobs:
           pkgver="${version//-/_}"
           tray="target/${{ matrix.gnu_target }}/release/tsunagi-tray"
           bash dist/deb/build-deb.sh \
-            "target/${{ matrix.target }}/release/tsunagi" \
+            "target/${{ matrix.target }}/release/tsng" \
             "${{ matrix.deb_arch }}" "$version" \
             "tsunagi-gui_${version}_${{ matrix.deb_arch }}.deb" "$tray"
           bash dist/arch/build-pkg.sh \
-            "target/${{ matrix.target }}/release/tsunagi" \
+            "target/${{ matrix.target }}/release/tsng" \
             "${{ matrix.pkg_arch }}" "$version" \
             "tsunagi-gui-${pkgver}-1-${{ matrix.pkg_arch }}.pkg.tar.zst" "$tray"
 
@@ -228,6 +274,7 @@ jobs:
             ${{ matrix.asset }}-*.*
             *.deb
             *.pkg.tar.zst
+            tsunagi-setup-*.exe
           if-no-files-found: error
 
   publish:
@@ -299,5 +346,5 @@ jobs:
               cat up.json >&2 || true
               rc=1
             fi
-          done < <(find artifacts -type f \( -name '*.tar.gz' -o -name '*.zip' -o -name '*.deb' -o -name '*.pkg.tar.zst' \) -print0)
+          done < <(find artifacts -type f \( -name '*.tar.gz' -o -name '*.zip' -o -name '*.deb' -o -name '*.pkg.tar.zst' -o -name 'tsunagi-setup-*.exe' \) -print0)
           exit "$rc"

.github/workflows/release.yml

@@ -47,7 +47,16 @@ jobs:
             deb: true
             deb_arch: arm64
             pkg_arch: aarch64
-            gnu_target: aarch64-unknown-linux-gnu
+          # 32-bit ARM with hardware float (ARMv7, `v7l`): single-board and edge
+          # devices. Statically linked like the others.
+          - os: ubuntu-latest
+            target: armv7-unknown-linux-musleabihf
+            asset: tsunagi-linux-armv7
+            archive: tar.gz
+            zig: true
+            deb: true
+            deb_arch: armhf
+            pkg_arch: armv7h
           - os: macos-latest
             target: aarch64-apple-darwin
             asset: tsunagi-macos-aarch64
@@ -101,9 +110,9 @@ jobs:
             # one lint to keep the musl build log clean. A real link error still
             # fails the build.
             export RUSTFLAGS="${RUSTFLAGS:-} -A linker_messages"
-            cargo zigbuild --release --locked --target "${{ matrix.target }}" --bin tsunagi
+            cargo zigbuild --release --locked --target "${{ matrix.target }}" --bin tsng
           else
-            cargo build --release --locked --target "${{ matrix.target }}" --bin tsunagi
+            cargo build --release --locked --target "${{ matrix.target }}" --bin tsng
           fi
 
       # The tray GUI. On Linux it is built against glibc (an old baseline for
@@ -113,11 +122,19 @@ jobs:
         shell: bash
         run: |
           set -euo pipefail
-          export RUSTFLAGS="${RUSTFLAGS:-} -A linker_messages"
           if [[ "${{ runner.os }}" == "Linux" ]]; then
-            rustup target add "${{ matrix.gnu_target }}"
+            if [[ -n "${{ matrix.gnu_target }}" ]]; then
-            cargo zigbuild --release --locked \
+              # tray-icon links GTK and libappindicator through pkg-config, which
-              --target "${{ matrix.gnu_target }}.2.28" --bin tsunagi-tray
+              # has no cross story under zig, so the Linux GUI is built natively
+              # (x86_64 only) against the runner's glibc.
+              sudo apt-get update
+              sudo apt-get install -y --no-install-recommends \
+                libgtk-3-dev libayatana-appindicator3-dev libxdo-dev
+              cargo build --release --locked \
+                --target "${{ matrix.gnu_target }}" --bin tsunagi-tray
+            else
+              echo "no GUI build for ${{ matrix.target }}"
+            fi
           else
             cargo build --release --locked --target "${{ matrix.target }}" --bin tsunagi-tray
           fi
@@ -131,15 +148,17 @@ jobs:
           stage="dist/pkg/${{ matrix.asset }}"
           mkdir -p "$stage"
 
-          bin="tsunagi"
+          bin="tsng"
-          [[ "${{ runner.os }}" == "Windows" ]] && bin="tsunagi.exe"
+          [[ "${{ runner.os }}" == "Windows" ]] && bin="tsng.exe"
           cp "target/${{ matrix.target }}/release/${bin}" "$stage/"
 
-          # The tray GUI alongside it: glibc build on Linux, native elsewhere.
+          # The tray GUI alongside it, where it was built (Linux: x86_64 only).
           tray="tsunagi-tray"
           [[ "${{ runner.os }}" == "Windows" ]] && tray="tsunagi-tray.exe"
           if [[ "${{ runner.os }}" == "Linux" ]]; then
-            cp "target/${{ matrix.gnu_target }}/release/${tray}" "$stage/"
+            if [[ -n "${{ matrix.gnu_target }}" ]]; then
+              cp "target/${{ matrix.gnu_target }}/release/${tray}" "$stage/"
+            fi
           else
             cp "target/${{ matrix.target }}/release/${tray}" "$stage/"
           fi
@@ -156,6 +175,10 @@ jobs:
             macOS)
               cp dist/macos/cy.hexor.tsunagi.plist "$stage/"
               cp dist/macos/README.md "$stage/INSTALL.md"
+              # The tray as an application bundle, for the Homebrew cask.
+              bash dist/macos/build-app.sh \
+                "target/${{ matrix.target }}/release/tsunagi-tray" \
+                "$version" "$stage/Tsunagi.app"
               ;;
             Windows)
               cp dist/windows/README.md "$stage/INSTALL.md"
@@ -169,6 +192,29 @@ jobs:
             tar -C dist/pkg -czf "${archive}" "${{ matrix.asset }}"
           fi
 
+      # The Windows installer: the agent as a service, Wintun, the tray and the
+      # PATH entry in one setup program. Wintun is the signed library from
+      # wintun.net, pinned by hash so a changed download fails the build.
+      - name: Build the Windows installer
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = 'Stop'
+          $version = $env:GITHUB_REF_NAME.TrimStart('v')
+          Invoke-WebRequest -Uri https://www.wintun.net/builds/wintun-0.14.1.zip -OutFile wintun.zip
+          $hash = (Get-FileHash wintun.zip -Algorithm SHA256).Hash
+          if ($hash -ne '07C256185D6EE3652E09FA55C0B673E2624B565E02C4B9091C79CA7D2F24EF51') {
+            throw "wintun.zip has an unexpected hash: $hash"
+          }
+          Expand-Archive wintun.zip -DestinationPath wintun-dl
+          choco install innosetup -y --no-progress
+          $iscc = Join-Path ${env:ProgramFiles(x86)} 'Inno Setup 6\ISCC.exe'
+          $stage = Join-Path $PWD 'dist/pkg/${{ matrix.asset }}'
+          & $iscc "/DAppVersion=$version" "/DSourceDir=$stage" `
+            "/DWintunDir=$(Join-Path $PWD 'wintun-dl/wintun/bin/amd64')" `
+            "/O$PWD" dist/windows/tsunagi.iss
+          if ($LASTEXITCODE -ne 0) { throw "ISCC failed with $LASTEXITCODE" }
+
       # A dependency-free .deb for the x86_64 and aarch64 Linux builds: it drops
       # the static binary, the systemd service and the polkit rule. Built with
       # dpkg-deb (present on the runner); see dist/deb/build-deb.sh.
@@ -179,7 +225,7 @@ jobs:
           set -euo pipefail
           version="${GITHUB_REF_NAME#v}"
           bash dist/deb/build-deb.sh \
-            "target/${{ matrix.target }}/release/tsunagi" \
+            "target/${{ matrix.target }}/release/tsng" \
             "${{ matrix.deb_arch }}" \
             "$version" \
             "tsunagi_${version}_${{ matrix.deb_arch }}.deb"
@@ -195,7 +241,7 @@ jobs:
           version="${GITHUB_REF_NAME#v}"
           pkgver="${version//-/_}"
           bash dist/arch/build-pkg.sh \
-            "target/${{ matrix.target }}/release/tsunagi" \
+            "target/${{ matrix.target }}/release/tsng" \
             "${{ matrix.pkg_arch }}" \
             "$version" \
             "tsunagi-${pkgver}-1-${{ matrix.pkg_arch }}.pkg.tar.zst"
@@ -203,7 +249,7 @@ jobs:
       # The GUI variants: the same agent plus the tray binary and a desktop
       # launcher, named tsunagi-gui (conflicting with the headless packages).
       - name: Build the GUI packages
-        if: matrix.deb
+        if: matrix.gnu_target
         shell: bash
         run: |
           set -euo pipefail
@@ -211,11 +257,11 @@ jobs:
           pkgver="${version//-/_}"
           tray="target/${{ matrix.gnu_target }}/release/tsunagi-tray"
           bash dist/deb/build-deb.sh \
-            "target/${{ matrix.target }}/release/tsunagi" \
+            "target/${{ matrix.target }}/release/tsng" \
             "${{ matrix.deb_arch }}" "$version" \
             "tsunagi-gui_${version}_${{ matrix.deb_arch }}.deb" "$tray"
           bash dist/arch/build-pkg.sh \
-            "target/${{ matrix.target }}/release/tsunagi" \
+            "target/${{ matrix.target }}/release/tsng" \
             "${{ matrix.pkg_arch }}" "$version" \
             "tsunagi-gui-${pkgver}-1-${{ matrix.pkg_arch }}.pkg.tar.zst" "$tray"
 
@@ -227,6 +273,7 @@ jobs:
             ${{ matrix.asset }}-*.*
             *.deb
             *.pkg.tar.zst
+            tsunagi-setup-*.exe
           if-no-files-found: error
 
   publish:
@@ -255,7 +302,7 @@ jobs:
 
           # download-artifact nests each artifact under its own directory, so
           # the archives are artifacts/<asset>/<file>.
-          mapfile -t files < <(find artifacts -type f \( -name '*.tar.gz' -o -name '*.zip' -o -name '*.deb' -o -name '*.pkg.tar.zst' \))
+          mapfile -t files < <(find artifacts -type f \( -name '*.tar.gz' -o -name '*.zip' -o -name '*.deb' -o -name '*.pkg.tar.zst' -o -name 'tsunagi-setup-*.exe' \))
           printf 'asset: %s\n' "${files[@]}"
 
           prerelease=()

AGENTS.md

@@ -8,7 +8,7 @@ before touching the code. Do not restate the full design here; follow the links.
 A proof-of-concept agent library for small private mesh networks. A user
 supplies a network name and one shared secret; agents derive the same network
 space independently, find each other, prove membership and exchange control
-messages. Scope and non-scope are in [README.md](README.md).
+messages. What it does and does not do is in [docs/architecture.md](docs/architecture.md) and [docs/threat-model.md](docs/threat-model.md).
 
 There is no central server, no owner, no registration and no majority vote.
 Design accordingly: a majority is not a root of trust.
@@ -30,7 +30,7 @@ scripts when improving the interactive workflow.
 Keep these separate. Crossing them is the main thing to review for.
 
 - **Control plane vs data plane.** The separation is **logical, not physical**.
-  The control protocol in `crates/tsunagi/src/proto/` knows nothing about
+  The control protocol in `crates/tsunagi-core/src/proto/` knows nothing about
   packets, and a protocol crate knows nothing about the control protocol;
   either can be replaced on its own. Both may ride on iroh — refusing to
   would throw away iroh's NAT traversal and force the data plane to
@@ -59,8 +59,10 @@ Keep these separate. Crossing them is the main thing to review for.
   other peers goes link in, link out: it is never written to the middle's
   interface or decrypted there. Multihop routing has a bounded hop limit;
   equal-cost next hops are chosen per flow. Reachability is first-hand and
-  volatile: each authenticated member advertises its own protocol-specific
+  volatile: each authenticated member advertises its own direct links, of
-  links. Build routing tables on topology changes, never per packet. Transit
+  whatever kind. A link is a way to reach a neighbour and a protocol is an
+  end-to-end tunnel to a peer; the two meet only in the envelope, so a
+  tunnel never depends on which transports carry it. Build routing tables on topology changes, never per packet. Transit
   must not acquire a routing mutex or wait for a protocol/TUN reader.
 - **Broadcast fanout belongs at local IP ingress.** Participation is local to
   each network, enabled by default, persisted and advertised to authenticated
@@ -70,9 +72,9 @@ Keep these separate. Crossing them is the main thing to review for.
   ownership checks or add broadcast flooding to encrypted transit.
 - **Plugins never learn reachability.** An `IpPlugin` is handed a `PacketLink`
   per peer and moves datagrams over it. Addresses, hole punching and relays
-  belong to `crates/tsunagi/src/dataplane/transport/`. A plugin announcement says *who*, never
+  belong to `crates/tsunagi-core/src/dataplane/transport/`. A plugin announcement says *who*, never
   *where*.
-- **The core never parses a plugin payload.** See `crates/tsunagi/src/dataplane/mod.rs`. Only
+- **The core never parses a plugin payload.** See `crates/tsunagi-core/src/dataplane/mod.rs`. Only
   `crates/tsunagi-wg-quic/src/announcement.rs` interprets `wg-quic` payloads, and
   only after bounding every field. A data plane failure must never stop the
   control plane.
@@ -81,7 +83,7 @@ Keep these separate. Crossing them is the main thing to review for.
   inbound packets are dropped unless their source is the address derived for
   the peer that sent them. Never trust an address a peer announces.
 - **Signed state is the only durable agreement.** A fact that must survive a
-  participant being away goes in `crates/tsunagi/src/state/` as a record signed by its
+  participant being away goes in `crates/tsunagi-core/src/state/` as a record signed by its
   author, never in a session. Merging is deterministic, an older version never
   rolls back a newer one, and absence from a snapshot is not deletion. Never
   add a vote or a quorum: a majority is not a trust root here, and it would
@@ -115,7 +117,7 @@ Keep these separate. Crossing them is the main thing to review for.
    normal path *and* the important failures. See [docs/testing.md](docs/testing.md).
    Do not add tests for getters or to move a coverage number.
 2. **Never change `IDENTITY_SCHEME`, the derivation labels, or the transcript
-   encoding** in `crates/tsunagi/src/identity/network.rs` and `crates/tsunagi/src/proto/handshake.rs` without
+   encoding** in `crates/tsunagi-core/src/identity/network.rs` and `crates/tsunagi-core/src/proto/handshake.rs` without
    treating it as an incompatible protocol change. Bumping the crate version or
    the control protocol version must not change an existing `NetworkId`.
 3. **Secrets never leak.** Not into logs, not into `Debug`, not into status
@@ -126,7 +128,7 @@ Keep these separate. Crossing them is the main thing to review for.
    the library; tests opt out explicitly at the top of each file.
 5. **Bounds before allocation.** Frame lengths are checked against
    `Limits::max_frame_len` before a buffer is allocated. Every string, list and
-   queue has a limit in `crates/tsunagi/src/config.rs`.
+   queue has a limit in `crates/tsunagi-core/src/config.rs`.
 6. **Failure is contained.** A bad signature, wrong secret, malformed packet or
    unknown version rejects one message or one session. It never stops another
    network and never stops the agent. There is no irreversible global error
@@ -150,18 +152,18 @@ Keep these separate. Crossing them is the main thing to review for.
 
 | path                | responsibility |
 |---------------------|----------------|
-| `crates/tsunagi/src/identity/`     | device identity; deterministic network space identity and derived keys |
+| `crates/tsunagi-core/src/identity/`     | device identity; deterministic network space identity and derived keys |
-| `crates/tsunagi/src/storage/`      | `state.sqlite`, `cache.sqlite`, directory ownership lock |
+| `crates/tsunagi-core/src/storage/`      | `state.sqlite`, `cache.sqlite`, directory ownership lock |
-| `crates/tsunagi/src/discovery.rs`  | candidate sources; test and static backends |
+| `crates/tsunagi-core/src/discovery.rs`  | candidate sources; test and static backends |
-| `crates/tsunagi/src/proto/`        | framing, message formats, membership handshake |
+| `crates/tsunagi-core/src/proto/`        | framing, message formats, membership handshake |
-| `crates/tsunagi/src/net.rs`        | iroh endpoint adapter and observability snapshots |
+| `crates/tsunagi-core/src/net.rs`        | iroh endpoint adapter and observability snapshots |
-| `crates/tsunagi/src/agent/`        | agent lifecycle, per-network runtimes, sessions, events, status |
+| `crates/tsunagi-core/src/agent/`        | agent lifecycle, per-network runtimes, sessions, events, status |
-| `crates/tsunagi/src/state/`        | signed records that outlive a session, their merge rules and address allocation |
+| `crates/tsunagi-core/src/state/`        | signed records that outlive a session, their merge rules and address allocation |
-| `crates/tsunagi/src/overlay/`   | the one interface an agent owns: provisioning, the TUN, routing, source checks, broadcast host rules |
+| `crates/tsunagi-core/src/overlay/`   | the one interface an agent owns: provisioning, the TUN, routing, source checks, broadcast host rules |
-| `crates/tsunagi/src/dataplane/` | the protocol contract and the authenticated packet transport |
+| `crates/tsunagi-core/src/dataplane/` | the protocol contract and the authenticated packet transport |
-| `crates/tsunagi/src/dns/`       | the DNS view of a network: zone, server, resolver publication |
+| `crates/tsunagi-core/src/dns/`       | the DNS view of a network: zone, server, resolver publication |
 | `crates/tsunagi-wg-quic/`       | the `wg-quic` protocol: its keys, its announcement, its tunnels |
-| `crates/tsunagi-cli/` | the command line agent; the only place that owns a runtime, a logger and signals |
+| `crates/tsunagi/` | the command line agent, built as `tsng`; the only place that owns a runtime, a logger and signals |
 | `tests/`            | integration tests; `tests/common/` is the shared harness |
 
 Add abstractions only at real substitution or testing boundaries. Do not add a

Cargo.lock

@@ -6234,6 +6234,28 @@ checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b"
 [[package]]
 name = "tsunagi"
 version = "0.1.0"
+dependencies = [
+ "anstream",
+ "anstyle",
+ "clap",
+ "iroh",
+ "netwatch",
+ "nix 0.31.3",
+ "simple-dns",
+ "tempfile",
+ "tokio",
+ "tracing",
+ "tracing-subscriber",
+ "tsunagi-core",
+ "tsunagi-tcp-tls",
+ "tsunagi-wg-quic",
+ "tsunagi-wireguard",
+ "windows-service",
+]
+
+[[package]]
+name = "tsunagi-core"
+version = "0.1.0"
 dependencies = [
  "arc-swap",
  "bytes",
@@ -6266,34 +6288,13 @@ dependencies = [
  "tokio-stream",
  "tracing",
  "tracing-subscriber",
- "tsunagi",
+ "tsunagi-core",
  "tun",
  "windows-sys 0.61.2",
  "zbus",
  "zeroize",
 ]
 
-[[package]]
-name = "tsunagi-cli"
-version = "0.1.0"
-dependencies = [
- "anstream",
- "anstyle",
- "clap",
- "iroh",
- "netwatch",
- "nix 0.31.3",
- "simple-dns",
- "tempfile",
- "tokio",
- "tracing",
- "tracing-subscriber",
- "tsunagi",
- "tsunagi-tcp-tls",
- "tsunagi-wg-quic",
- "tsunagi-wireguard",
-]
-
 [[package]]
 name = "tsunagi-tcp-tls"
 version = "0.1.0"
@@ -6318,7 +6319,7 @@ dependencies = [
  "tokio-rustls",
  "tracing",
  "tracing-subscriber",
- "tsunagi",
+ "tsunagi-core",
  "x25519-dalek",
  "zeroize",
 ]
@@ -6329,11 +6330,12 @@ version = "0.1.0"
 dependencies = [
  "eframe",
  "egui-phosphor",
+ "gtk",
  "tokio",
  "tracing",
  "tracing-subscriber",
  "tray-icon",
- "tsunagi",
+ "tsunagi-core",
  "winit",
 ]
 
@@ -6358,7 +6360,7 @@ dependencies = [
  "tokio",
  "tracing",
  "tracing-subscriber",
- "tsunagi",
+ "tsunagi-core",
  "zeroize",
 ]
 
@@ -6382,7 +6384,7 @@ dependencies = [
  "tokio",
  "tracing",
  "tracing-subscriber",
- "tsunagi",
+ "tsunagi-core",
  "zeroize",
 ]
 
@@ -7134,6 +7136,17 @@ dependencies = [
  "windows-link",
 ]
 
+[[package]]
+name = "windows-service"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "857224b3b211c6f3616921f081ee54721ee3ad2ace2fac6a6337e032f7b4dcf2"
+dependencies = [
+ "bitflags 2.13.2",
+ "widestring",
+ "windows-sys 0.61.2",
+]
+
 [[package]]
 name = "windows-strings"
 version = "0.1.0"

Cargo.toml

@@ -14,8 +14,8 @@ mainline = { path = "vendor/mainline" }
 [workspace.package]
 edition = "2024"
 rust-version = "1.91"
-license = "MIT OR Apache-2.0"
+license = "WTFPL"
-repository = "https://github.com/tsunagi-net/tsunagi"
+repository = "https://github.com/house-of-vanity/tsunagi"
 
 [workspace.lints.rust]
 missing_docs = "warn"

LICENSE

@@ -0,0 +1,13 @@
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+                    Version 2, December 2004
+
+ Copyright (C) 2004 Sam Hocevar <sam@hocevar.net>
+
+ Everyone is permitted to copy and distribute verbatim or modified
+ copies of this license document, and changing it is allowed as long
+ as the name is changed.
+
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. You just DO WHAT THE FUCK YOU WANT TO.

README.md

@@ -1,766 +1,184 @@
-# tsunagi
+<p align="center">
-
+  <img src="dist/linux/tsunagi.svg" width="96" alt="">
-A proof-of-concept Rust library for **small private mesh networks** — a handful
+</p>
-of friends, home machines, a few servers. Units to dozens of participants, not
+
-thousands.
+<h1 align="center">tsunagi</h1>
-
+
-The end user configures exactly two things:
+<p align="center">
-
+  <b>A mesh VPN with no server.</b><br>
-```text
+  Pick a network name, share a secret, and your machines are on one private network.
-network_name
+</p>
-secret          # one shared secret; "password" and "secret" mean the same value
+
-```
+<p align="center">
-
+  <a href="https://github.com/house-of-vanity/tsunagi/releases/latest"><img alt="release" src="https://img.shields.io/github/v/release/house-of-vanity/tsunagi?include_prereleases"></a>
-From those, every agent independently derives the same network space. There is
+  <a href="https://github.com/house-of-vanity/tsunagi/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/house-of-vanity/tsunagi/actions/workflows/ci.yml/badge.svg"></a>
-no central server, no network owner with special powers, no registration and no
+  <a href="LICENSE"><img alt="license" src="https://img.shields.io/badge/license-WTFPL-blue"></a>
-majority vote. Anyone who knows the parameters can join; nobody has to trust
+</p>
-anybody else.
+
-
+```console
-## What this proof of concept actually does
+laptop$ tsng join -n home
-
+joined `home`
-A working library with **real iroh connections** and integration tests:
-
-- persistent device identity stored in SQLite, stable across restarts;
-- several independent networks at once in one agent;
-- deterministic network identity derived from name + secret;
-- candidates supplied by a replaceable discovery component;
-- automatic first contact through the public Mainline DHT (BEP44);
-- real iroh connections plus an explicit mutual proof of network membership;
-- a small versioned control protocol: handshake, hostname/capability
-  announcement, ping/pong;
-- automatic reconnect with bounded exponential backoff and jitter;
-- status snapshots, an event stream and honest diagnostics;
-- configuration restored after a restart;
-- correct behaviour when the disposable cache is missing or corrupt;
-- a **WireGuard data plane**, in userspace: its own key per network, an IPv6
-  overlay with deterministically derived addresses and optional IPv4, real
-  tunnels carried over iroh, and address ownership enforced rather than
-  believed;
-- a **command line agent**, `tsunagi`, with a local control socket.
-
-### What it deliberately does **not** do
-
-Not implemented, and not pretended to be: DNS, routing through
-intermediate participants, a full CRDT, dynamically loaded plugins, a system
-service, a complete CLI, or a local control socket. Snapshot synchronisation
-and signed revocations are designed for but not implemented — see
-[docs/sync-model.md](docs/sync-model.md). The WireGuard plugin's own limits,
-including that its system backend is Linux-only, are in
-[docs/wireguard.md](docs/wireguard.md#limits-and-future-work).
-
-**Control and data are separated logically, not physically.** Both ride on
-iroh, on different ALPNs and different connections, so the data plane inherits
-iroh's hole punching and relay fallback instead of reimplementing them — while
-the control protocol still knows nothing about packets and can keep a different
-transport underneath it later. Filtering user traffic remains the operating
-system's and the user's responsibility, not this library's.
-
-## Requirements
-
-- Rust 1.91 or newer (iroh 1.2 requires it), edition 2024. Pinned dependencies
-  in `Cargo.lock`.
-- No internet, no public DHT, no public relay, no administrator rights and no changes
-  to OS network settings are needed to build or test.
-- WireGuard runs in userspace (boringtun): **no kernel module and no `wg`
-  tool**. Only creating a real network interface needs `CAP_NET_ADMIN`, and
-  `--no-tun` skips even that.
-
-## Trying it on two machines
-
-On the first machine:
-
-```bash
-cargo build --release
-./target/release/tsunagi status          # this device, the agent, and this host
-./target/release/tsunagi network         # the networks this device belongs to
-```
-
-Two commands do the work, and they are separate on purpose: `up` runs the
-agent — one per device, for as long as you want it — and `join` decides
-what it belongs to, at any time, while it runs.
-
-```bash
-# Terminal one: the agent. It prints its endpoint id and then serves.
-./target/release/tsunagi up
-
-# Terminal two: make a network. With no --secret it invents one and prints
-# it, along with the line to send the other machine.
-./target/release/tsunagi join --network lab
-```
-
-On the second machine, start its agent and join the same network with the
-secret that was printed:
-
-```bash
-./target/release/tsunagi up
-./target/release/tsunagi join --network lab --secret tsn1...
-```
-
-**Name and secret are enough for the first meeting.** Mainline DHT discovery
-is enabled by default. Each active network publishes this device's endpoint
-and searches until the first authenticated connection. While connected it
-only republishes; after 60 seconds without any authenticated connection it
-searches again. Publication is approximately every five minutes, and records
-older than 15 minutes are ignored. DHT storage nodes may retain them longer.
-
-Use `--no-dht` to disable DHT, or `--peer <endpoint-id>` for optional manual
-bootstrap. `--reach local` disables public DHT regardless of the DHT flag.
-Endpoint records are public, signed, and contain no network secret. Discovery
-is not authentication: every connection must still prove network membership.
-Details and failure behavior are in [docs/mainline-dht.md](docs/mainline-dht.md).
-
-**One introduction is enough for the whole network.** Members tell each
-other about the members they know, and every author of a signed record is
-somebody to try, so a device pointed at one member ends up talking to all
-of them rather than to the one that happened to be on its command line.
-What travels is a candidate — an address somebody has seen — and it is
-authenticated by the handshake like any other; being introduced grants
-nothing. It is deliberately the same shape a lookup in a distributed hash
-table would return, so that is a source to add beside this one rather than
-a redesign.
-
-An agent with nobody to contact says so in `status` rather than sitting
-there looking patient.
-
-Within a few seconds both print something like:
-
-```text
-  + peer b47c958462 connected over direct rtt=Some(4.5ms)
-  + data link to b47c958462 for wg-quic: direct via 192.0.2.7:41234, datagram 1382
-
---- status ---
-control: 1 peer(s), 0 dial failure(s), 0 handshake failure(s)
-wg-quic: tsun0 on 10.13.37.69/24 mtu 1280, 1/1 tunnel(s) established
-  4jO4kx9Z 10.13.37.237 handshake 3s ago tx=0 rx=0 dropped=0 path=direct via 192.0.2.7:41234
-```
-
-`1/1 tunnel(s) established` means a real WireGuard handshake completed.
-
-## Checking that it works
-
-From another shell on either machine:
-
-```bash
-tsunagi status
-```
-
-```text
-endpoint  7d76ccbbc21bf30767e14422c0494740a2cecc02aa9f82d5b8d57bdae350e7fc
-hostname  tsunagi-7d76ccbbc2
-bound     0.0.0.0:41641
-
-network lab (z2o4qwrvnj3zb6st2aoqg4abf342j662q2ujttqrsmz22argk2ba)  active
-  peer b345d5271b  tsunagi-b345d5271b  Direct  rtt 24ms
-  overlay tsunz2o4qwrvnj3 fd09:…:c1c6/64 and 100.110.49.177 mtu 1280  1/1 tunnel(s) up
-    SDsEb/WF  fd09:…:c4b / 100.65.243.53  handshake 4s ago  tx 0 rx 0  Direct via Ip(…)
-```
-
-`1/1 tunnel(s) up` and a recent handshake mean the tunnel is live. Then send
-real traffic to the peer's overlay address:
-
-```bash
-ping6 fd09:…:c4b        # or
-ping  100.65.243.53
-```
-
-`tx` and `rx` in the status should start moving.
-
-**Addresses are allocated and then remembered.** The default range is
-`10.13.37.0/24`; the first member to join settles it and later members adopt
-what they find, so `--ipv4-range` only matters for whoever starts the network:
-
-```bash
-tsunagi up --ipv4-range 10.44.0.0/16
-tsunagi up --ipv4-range none   # no data plane at all
-```
-
-One agent has one interface, so two of its networks cannot both use that
-range. The second takes the range **derived from its own network id**: not
-picked locally — every member derives the same one from something they all
-already have — so it is an agreement rather than a guess, and a device in
-several networks gets an address in each.
-
-An address is claimed with a record signed by that member's persistent device
-key, stored, and merged between every replica. A member that disappears for a
-month comes back to the same address, because the claim outlived the session.
-No vote is involved — see
-[docs/wireguard.md](docs/wireguard.md#ipv4-allocated-signed-and-kept) and
-[docs/sync-model.md](docs/sync-model.md).
-
-Because the address is allocated at run time rather than derived, it is not
-known until the agent has started and agreed with its peers. The agent then
-assigns it to the interface itself.
-
-## Levels
-
-The command line is split the way the design is. A bare `tsunagi up` needs
-only a network name and a secret; everything else sits under the level it
-belongs to, which `--help` shows as two sections:
-
-* **System** — what the agent itself does: how it reaches peers (`--reach`),
-  the one overlay interface it owns (`--interface`, `--mtu`, `--no-tun`), the
-  address range (`--ipv4-range`), and the local resolver (`--no-dns` to disable).
-* **Transport** — which protocols carry packets (`--protocol`, a list) and
-  their own settings (`-o key=value`, or `-o protocol:key=value`).
-
-```bash
-tsunagi protocols          # what this build can carry packets with
-```
-
-```text
-wg-quic  (wire version 4)
-        what                  WireGuard's cryptography carried in iroh's QUIC datagrams
-        -o keepalive=SECONDS  keeps a tunnel and its link warm through a NAT
-        -o mtu=BYTES          largest packet a tunnel will carry, at least 576
-```
-
-Each protocol declares its own settings, so the agent can list them without
-knowing anything about the protocol, and a setting no selected protocol takes
-is refused rather than ignored. `--protocol none` runs the control plane by
-itself.
-
-A pair of peers uses a protocol they both have **at the same wire version**.
-That is not the software version: two peers on different builds carry traffic
-for each other for as long as the bytes between them have not changed. A peer
-with nothing in common keeps its control plane — messages and signed state
-still flow — and simply has no data plane, which `tsunagi status` shows as a
-session with no agreed protocol.
-
-## Names
-
-DNS is enabled by default and serves a local zone for **every network this device is in**,
-each named after the network, so members can be reached by name instead of
-by address:
-
-```bash
-tsunagi up               # DNS is already enabled
-dig @127.0.0.1 -p 5354 music.lab
-```
-
-An explicit choice is remembered across restarts. `--no-dns` or `tsunagi dns off`
-disables it; `--dns` or `tsunagi dns on` enables it again. Existing saved opt-outs
-remain respected. The `dns on` and `dns off` commands also take effect immediately
-on a running agent. `--dns` and `--no-dns` cannot be combined.
-
-The zone of a network is its name — `--dns-zone` is gone, because with
-several networks there is no single zone to name. A network name may contain
-dots, so `--network lab.internal` is how you get `music.lab.internal`.
-
-Names come from signed state, which is the point: **a member that is
-switched off still resolves**, because its claim outlived the session.
-
-The answers are IPv4 addresses, because that is what the overlay is. The
-*questions* are taken on `127.0.0.1` and `[::1]`, over UDP and TCP, so a
-resolver reaches it over whichever family it uses; both are published to the
-system resolver together. Loopback and nothing else: the zones are a view
-for the host running the agent, and binding an overlay address would put
-them in front of the whole mesh — an agent in two networks would then answer
-one network's questions about the other's names.
-
-The zone is the network name, and it is yours to choose. A name that
-shadows a real public domain is reported and then used: a network called
-`ru` warns that every public `.ru` name becomes unreachable from this host,
-and then does it. Anything that collides with nothing — which is most names
-— is said nothing about, because a warning that fires on every private name
-anybody picks is how people learn to ignore warnings.
-
-On Linux the agent tells systemd-resolved to send questions for that suffix
-here, over D-Bus, scoped to the overlay interface and as a *routing* domain
-so it never becomes the resolver for anything else. resolved drops the whole
-setting when the interface goes, and the interface goes with the agent.
-
-Only an interface the agent created, though. Under `--no-tun` there is no
-host interface at all, and the agent says so and serves the zone on
-loopback rather than configuring whatever else on the host happens to share
-the name.
-
-That last step needs permission that `CAP_NET_ADMIN` does not give:
-systemd-resolved asks polkit, and polkit decides by **user**, not by
-capability, so there is no way for the agent to arrange it from inside. On
-a desktop the refusal reads `Interactive authentication required`.
-
-Running as a system service is enough. Otherwise the agent prints the rule
-that grants it — the four actions it calls and nothing else — ready to
-paste:
-
-```bash
-sudo tee /etc/polkit-1/rules.d/50-tsunagi-resolved.rules > /dev/null <<'RULE'
-polkit.addRule(function(action, subject) {
-    var allowed = [
-        "org.freedesktop.resolve1.set-dns-servers",
-        "org.freedesktop.resolve1.set-domains",
-        "org.freedesktop.resolve1.set-default-route",
-        "org.freedesktop.resolve1.revert"
-    ];
-    if (allowed.indexOf(action.id) >= 0 && subject.user == "YOUR-USER") {
-        return polkit.Result.YES;
-    }
-});
-RULE
-```
-
-**Without it the server still runs** — `tsunagi status` prints where it is
-listening and the exact `dig` line — so the automatic part is missing, not
-the feature. The refusal is said once rather than on every pass, and retried
-slowly, because nothing but a person will change it.
-
-The server is authoritative for its zone and nothing else. No recursion, no
-forwarding, no cache: pointing a resolver at it can never make it a route to
-the outside.
-
-## Privileges
-
-On Linux the agent **manages its own overlay interface**. It creates the TUN
-interface, sets the MTU, brings it up and assigns both overlay addresses, all
-over netlink in process — no `ip` invocation, no shell, nothing that a
-remote peer could influence.
-
-That needs `CAP_NET_ADMIN`, granted once:
-
-```bash
-sudo setcap cap_net_admin+p /usr/local/bin/tsunagi
-```
-
-`+p` rather than `+ep`: the capability is then *permitted* but not
-*effective*, and the agent raises it only around the handful of netlink calls
-that need it — a few milliseconds at startup, and again if its address
-allocation changes. Everything else, including every byte from the network,
-is handled with it lowered. `+ep` works too; the agent lowers it on the way
-in.
-
-`tsunagi status` says which of these applies on the host it runs on, along
-with what the agent is doing. It grades each finding: **ok** for what works,
-**warn** for what the agent runs without and you can fix from the line it
-prints, **FAIL** for what it cannot work around. The words carry the grade as
-well as the colour, so the report reads the same piped to a file or on a
-terminal without colour, and it honours `NO_COLOR`.
-
-Members are listed online first, then the ones that are away. A member that
-is away is reported plainly rather than flagged: in a mesh of laptops it is
-the ordinary condition, not a fault. The signed state is what makes that
-sayable — it remembers who belongs while they are gone, so the report can say
-"offline, 10.13.37.99 still reserved for it" instead of leaving a
-dial-failure counter to imply it. Counters are history and are never graded:
-a peer that left and came back should not leave the report looking broken.
-
-The other two commands split along the line the system itself draws. `id` is
-this **device**: the key it signs with and the name it answers to. `network`
-is what it **belongs to**: which networks, their secrets, joining and
-leaving. A device outlives every network it is in, and a network outlives
-any device in it, so a command that mixed them had to be read twice.
-
-Every item takes the same shape, so there is nothing to remember: name it to
-see it, name it with a value to change it.
-
-```
-tsunagi id                      everything about this device
-tsunagi id hostname             the name it answers to
-tsunagi id hostname mango       change it
-tsunagi id key                  the key it signs with
-tsunagi id key rotate           replace that key
-
-tsunagi network                 the networks this device belongs to
-tsunagi network join -n lab -s tsn1…   join one; adds it to a running agent
-tsunagi network join -n lab     resume one this device has, or make it on the spot
-tsunagi network stop lab        stop serving it, keeping everything
-tsunagi network start lab       serve it again, from where it left off
-tsunagi network leave lab       give up the address and name, then forget it
-tsunagi network secret          the secret of each joined network
-tsunagi network secret lab      just that one, for copying
-tsunagi network secret generate a fresh secret for a network that does not exist yet
-
-tsunagi dns                     whether the local resolver is serving, and what
-tsunagi dns on                  start it, now and after every restart
-tsunagi dns off                 stop it, now and after every restart
-```
-
-**A network without a secret makes one.** `tsunagi join --network lab`
-resolves a bare name in the obvious way: if this device is already in
-exactly one network called `lab`, that one — so the name alone resumes what
-you have; if it is in none, a fresh random secret, printed in full with the
-line to send the other machine:
-
-```
-joined `lab` (k2on43wadbi5x267vp6z3ogkm7nbjedfdoxyauxhtxhwqrprylba)
   secret  tsn1u7c…
 
-Run this on the other machine:
+server$ tsng join -n home -s tsn1u7c…
+server$ tsng id hostname server
 
-  tsunagi join --network lab --secret tsn1u7c…
+laptop$ ssh server.home
-
-Its agent has to be running. If it is not:
-
-  tsunagi up --peer 91e83a6e2b7a…
 ```
 
-Two networks of one name is a thing that happens — a mistyped secret makes
+No account, no coordination server, no admin console, no keys to approve.
-one — so joining says whether the network was already here, and warns when
+Anyone who knows the **name** and the **secret** is in. Nobody else can find
-another configured network answers to the same name. A name is a label and
+the network, let alone enter it.
-the id is the identity.
 
-That is the ad-hoc case: one person makes a network and sends the command
+## Why
-round. The secret is printed *only* when the agent invented it — there is
-nowhere else to read it from — and never when it was supplied, because then
-it is already yours. Two networks of one name and no secret is the one case
-with no answer, and it says so instead of choosing.
 
-A secret is printed by `network secret` and nowhere else — not by `id`, not
+Tailscale, Headscale and ZeroTier are great, but each needs a control server:
-by `status`, not in a log, a `Debug` rendering or anything sent to a peer.
+theirs, or one you have to run and keep alive. tsunagi doesn't. Machines find
-Asking for it is deliberate, because these reports get pasted into chats.
+each other through the public BitTorrent DHT, connect directly (hole punching,
+with relay fallback), and keep the network state among themselves.
 
-**`up` takes no network at all** if you would rather decide later: it
+|                        | Tailscale          | Headscale        | ZeroTier            | **tsunagi**         |
-brings up the agent and whatever it is already configured for, and waits.
+| ---------------------- | ------------------ | ---------------- | ------------------- | ------------------- |
-That is the shape of a daemon in one terminal and `tsunagi network join`
+| Control server         | hosted by vendor   | you run it       | hosted or self-run  | **none**            |
-in another.
+| Account / sign-in      | yes                | yes              | yes                 | **no**              |
+| To join a network      | sign in, get approved | pre-auth key  | network ID, approval | **name + secret**  |
+| Direct connections     | yes                | yes              | yes                 | yes                 |
+| Exit nodes             | yes                | yes              | via routes          | yes                 |
 
-`network join` is also the answer to a question `up` cannot: a state
+## Features
-directory belongs to one live agent, so a second `tsunagi up` cannot add a
-network to the one already running. This adds it over the control socket and
-it starts at once. With no agent running it is written to the configuration
-and starts with the next `up`.
 
-The name is part of the signed state, so changing it revokes the previous
+- **Two things to know:** a network name and a secret. A secret is generated for you when you make a network.
-one: there is one record per author, a new version replaces the whole claim,
+- **Direct, encrypted links** between members (WireGuard cryptography), with relay fallback behind strict NATs.
-and no replica can keep the old name standing. Changing it while the agent
+- **Names for machines:** `server.home` just works, even while `server` is switched off. A name belongs to whoever claimed it first; a later device with the same name keeps working by address and is told so.
-runs goes through the agent, which republishes and tells its peers straight
+- **Exit nodes:** send all your internet traffic through any member that offers one.
-away.
+- **Multi-hop:** members that can't reach each other directly are routed through a member that can, over whatever kind of link each hop has. A member reached that way is online, and shown as relayed; traffic moves to a direct link by itself the moment one comes up.
+- **LAN games:** UDP broadcasts are relayed, so "LAN" lobbies show up across the mesh.
+- **Several networks at once** on one device.
+- **Tray app** for Windows, macOS and Linux; a command line for everything.
 
-Replacing the signing key makes this device a different member, and it loses
+## Install
-the address and name the old key held — nothing can sign on a retired key's
-behalf, and by design there is no authority that could overrule an author. So
-the outgoing key signs a release for every network on its way out, which
-frees them for whoever wants them next, and the whole thing commits at once.
 
-`status` and `id` both prefer a running agent, which is live and
+Grab a build from the [latest release](https://github.com/house-of-vanity/tsunagi/releases/latest).
-authoritative, and fall back to reading the state store when there is none.
-Reading takes no directory lock, so neither has to wait for the agent it is
-asking about — nor does either need one to be running.
 
-### It cleans up after itself
+| Platform              | How                                                                              |
+| --------------------- | -------------------------------------------------------------------------------- |
+| **Windows**           | Run `tsunagi-setup-<version>-x86_64.exe`. Installs the service, the tray and `tsng`. |
+| **macOS**             | `brew tap house-of-vanity/tap && brew install --cask tsunagi-gui`<br>CLI only: `brew install tsunagi` |
+| **Debian / Ubuntu**   | `sudo apt install ./tsunagi-gui_<version>_amd64.deb` (`tsunagi_…` for no tray)   |
+| **Arch**              | `sudo pacman -U tsunagi-gui-<version>-1-x86_64.pkg.tar.zst`                      |
+| **NixOS**             | [Flake and module](#nixos) below                                                 |
+| **Any other Linux**   | Unpack the tarball, then `sudo ./install.sh && sudo systemctl enable --now tsunagi` |
 
-The interface is tied to an open file descriptor and is deliberately **not**
+Linux packages run the agent as an unprivileged service user. Add yourself to
-made persistent, so the kernel removes it when the agent exits — on a clean
+the `tsunagi` group (`sudo usermod -aG tsunagi $USER`, then log in again) to
-shutdown, on a panic, on `SIGKILL`, on power loss alike. Keeping it is what
+use `tsng` and the tray without `sudo`.
-would take an action; removing it is the default.
 
-If something is left behind anyway — an interface made by an older version's
+## Quick start
-manual recipe, or one from a run killed in the instant between creating it and
-recording it — the next start **replaces it**, along with any stale addresses
-it carried. Two things are never touched:
 
-* an interface that is not a TUN, because the name colliding with somebody's
+```sh
-  bridge is not a reason to destroy the bridge;
+tsng join -n home                 # first machine: makes the network and prints a secret
-* a TUN that another process is holding open, because that is a working
+tsng join -n home -s tsn1…        # every other machine
-  overlay belonging to somebody else — most likely a second agent on this
+tsng status                       # who is online, over which path
-  host, which should be given a different `--wg-prefix`.
-
-Both of those refuse with an explanation rather than guessing.
-
-Two settings the manual recipe used to need are gone with it.
-`keep_addr_on_down` existed only because an interface nobody held open lost
-carrier and had its IPv6 addresses flushed, and `nodad` only because duplicate
-address detection can never finish without carrier. An interface held open for
-its whole life has carrier for its whole life.
-
-### The MTU is 1280
-
-The default interface MTU stays at 1280 on direct paths, relays and paths
-inside another VPN. Large encrypted packets are split into smaller QUIC
-datagrams and reassembled before reaching WireGuard. SSH and full-size TCP
-segments therefore do not require a manual MTU override or MSS adjustment.
-The original IP packet, including its DF bit, is preserved. See
-[docs/wireguard.md](docs/wireguard.md#mtu) for limits and compatibility.
-
-### Summary
-
-| approach | agent runs as | notes |
-|---|---|---|
-| `setcap cap_net_admin+p` | ordinary user, one capability | recommended: nothing to prepare, nothing left behind. Lost on every rebuild or copy of the binary. |
-| systemd service | `User=`, `AmbientCapabilities=CAP_NET_ADMIN` | the same, for an installed service |
-| `sudo tsunagi up` | root | everything works, nothing is isolated |
-| macOS root LaunchDaemon | root | the native macOS deployment; see below |
-| `--no-tun` | ordinary user, no capabilities | tunnels run and handshake, traffic never reaches the OS |
-
-On Windows, put `wintun.dll` beside the executable and start `tsunagi up`
-from PowerShell or Command Prompt opened with **Run as administrator**.
-Run commands controlling that agent (`join`, `status`, `dns`, `network`)
-as the same Windows user with the same elevation. If Windows denies access
-to the agent's control pipe, the command reports a permission error instead
-of claiming the agent is absent or trying to edit its locked state.
-Creating a TUN without sufficient privileges also explains how to restart
-the agent with the required permissions.
-
-On macOS the agent creates a `utun` interface, configures it with `ifconfig`
-and `route`, and points the system resolver at the overlay by writing
-`/etc/resolver/<network>` files (which carry a port, so the DNS server needs no
-privileged socket). All of this needs **root**: macOS has no per-capability
-grant like Linux, and a `utun` plus `/etc/resolver` are root-only. The kernel
-assigns the interface its `utunN` name, so the name derived from the network id
-is only a request and the real one is adopted once the interface is up.
-
-Run it as root — `sudo tsunagi up` for a quick start, or install it as a root
-**LaunchDaemon** for the native always-on deployment. As a daemon the agent runs
-unprivileged commands (`join`, `status`, `dns`, `network`) over its control
-socket like any other platform; the socket lives at `/var/run/tsunagi/agent.sock`
-and the stores at `/var/db/tsunagi`, both fixed system paths so they do not
-depend on whose shell started `sudo`. A ready-to-edit plist and install notes
-are in [dist/macos/](dist/macos/). The broadcast route is installed; the
-inbound-UDP firewall allowance (a `pf` anchor) is not yet, so `status` reports
-that half as incomplete and names what to allow by hand. The decision logic that
-says *what* to change is shared and tested on every platform.
-
-## Checks
-
-```bash
-cargo fmt --all -- --check
-cargo clippy --locked --workspace --all-targets -- -D warnings
-cargo test --locked --workspace --all-targets
 ```
 
-The whole suite runs offline on loopback. Set `TSUNAGI_TEST_LOG=tsunagi=debug`
+Every member gets an address in `10.13.37.0/24` and a name like `<host>.home`.
-to see agent logs while a test runs.
+Machines are called `tsunagi-<id>` until you rename them: `tsng id hostname laptop`.
 
-There are also two runnable demos, which are demos and not substitutes for the
+### Exit nodes
-tests:
 
-```bash
+```sh
-cargo run --example two_agents       # control plane only
+tsng network exit-node home on    # on the machine that should be the exit
+tsng exit-node                    # on another one: who offers an exit
+tsng exit-node laptop             # send everything through it
+tsng exit-node off
 ```
 
-Both run with no privileges and change nothing on the host.
+The tray does the same with a checkbox. An exit node sees everything you send
+through it, so use only members you trust.
+[Details and per-OS notes](docs/exit-node.md).
 
-## Usage
+## Platforms
 
-```rust,no_run
+| Platform                  | Build        | CLI `tsng` | Tray | Exit node: offer / use | Packages                            |
-use std::sync::Arc;
+| ------------------------- | ------------ | :--------: | :--: | :--------------------: | ----------------------------------- |
-use tsunagi::config::{AgentConfig, StoragePaths, TransportPolicy};
+| Linux x86_64              | release      |     ✔      |  ✔   |        ✔ / ✔           | `.deb`, `.pkg.tar.zst`, tarball, Nix |
-use tsunagi::discovery::SharedMemoryDiscovery;
+| Linux aarch64             | release      |     ✔      |  –¹  |        ✔ / ✔           | `.deb`, `.pkg.tar.zst`, tarball, Nix |
-use tsunagi::identity::{NetworkName, NetworkSecret};
+| Linux armv7               | release      |     ✔      |  –¹  |        ✔ / ✔           | `.deb`, `.pkg.tar.zst`, tarball      |
-use tsunagi::proto::ControlMessage;
+| macOS, Apple silicon      | release      |     ✔      |  ✔   |        ✔ / ✔²          | Homebrew, tarball                    |
-use tsunagi::{Agent, Result};
+| macOS, Intel              | from source  |     ✔³     |  ✔³  |        ✔ / ✔²³         | –                                    |
+| Windows x86_64            | release      |     ✔      |  ✔   |        ✔ / ✔²          | installer, zip                       |
 
-// The library never starts a runtime, installs a logger, handles signals,
+<sup>¹ Not in the release; builds from source (and through Nix).
-// forks, or calls process::exit. The binary owns all of that.
+² Newer and less battle-tested than on Linux.
-#[tokio::main]
+³ Builds from source, not covered by CI.</sup>
-async fn main() -> Result<()> {
-    let config = AgentConfig::new(StoragePaths::user_default()?)
-        .with_transport(TransportPolicy::N0Defaults)
-        .with_discovery(Arc::new(SharedMemoryDiscovery::new()));
 
-    let agent = Agent::spawn(config).await?;
+The Linux CLI is a single static binary: it runs on any distribution.
 
-    let name = NetworkName::new("kitchen-table")?;
+## NixOS
-    let secret = NetworkSecret::generate();       // 32 random bytes
-    println!("share this: {}", secret.encode().as_str());
 
-    let network = agent.join_network(&name, &secret).await?;
+The repository is a flake with a package and a module.
 
-    let mut events = agent.subscribe();
+```nix
-    tokio::spawn(async move {
+# flake.nix
-        while let Ok(event) = events.recv().await {
+{
-            println!("{event:?}");
+  inputs.tsunagi.url = "github:house-of-vanity/tsunagi";
+
+  outputs = { nixpkgs, tsunagi, ... }: {
+    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
+      modules = [
+        tsunagi.nixosModules.default
+        {
+          services.tsunagi = {
+            enable = true;
+            tray.enable = true;      # optional, for desktops
+            users = [ "alice" ];     # may use tsng and the tray without sudo
+          };
         }
-    });
+      ];
-
+    };
-    for peer in agent.network_status(network).await?.connected_peers() {
+  };
-        agent
-            .send(network, peer, ControlMessage::Ping { seq: 1, payload: vec![] })
-            .await?;
-    }
-
-    agent.shutdown().await;
-    Ok(())
 }
 ```
 
-`TransportPolicy::LocalOnly` is the default, so a plain `AgentConfig::new` never
+Just trying it: `nix run github:house-of-vanity/tsunagi#tsunagi-cli -- --help`.
-reaches the internet by accident. Opt into `DirectOnly` or `N0Defaults`
+`packages.<system>.tsunagi` (with the tray) and `tsunagi-cli` are also exported,
-explicitly.
+along with `overlays.default`.
 
-### Through somebody in the middle
+## Build from source
 
-Tsunagi routes the overlay in userspace. A direct data link always wins;
+Rust 1.91 or newer.
-otherwise the shortest available path can pass through several members.
-Each authenticated member advertises only its own live, protocol-specific
-transport links. The control plane collects these into a graph and replaces
-the routing table when connectivity changes; announcements expire after
-90 seconds without refresh.
-
-Transit goes transport → router → transport, without entering WireGuard or
-the intermediate host's TUN. The payload stays encrypted between the original
-endpoints. TUN connects only the local OS to Tsunagi; the kernel needs only
-the overlay route through that interface, with no IP forwarding configuration.
-
-A 16-hop limit bounds loops while topology updates converge. Equal shortest
-paths use a stable flow hash derived before encryption, so packets of a TCP
-or UDP flow keep their path while topology is unchanged. Physical link changes
-do not replace end-to-end WireGuard tunnels or change the 1280-byte default MTU.
-`status` reports the hop count and first next hop for relayed paths.
-
-The hot path reads an immutable routing snapshot and sends directly to a cached
-transport handle. It takes no routing mutex, walks no graph and does not parse
-the encrypted payload. See [routing.md](docs/routing.md) for the architecture,
-limits and reproducible forwarding microbenchmark.
-
-This wire format requires all members to upgrade together (control ALPN 3,
-data ALPN 4); saved identities, network names, secrets and addresses survive.
-
-### LAN game discovery
-
-IPv4 UDP broadcast relay is enabled by default for each network. The IP router
-sends one encrypted copy to each participating peer, including through multihop
-paths. It supports `255.255.255.255` and the overlay subnet's broadcast address;
-received broadcasts never trigger another fanout.
 
 ```sh
-tsunagi join -n games --no-broadcast
+cargo build --release --bin tsng               # the agent and CLI
-tsunagi join -n games --broadcast
+cargo build --release --bin tsunagi-tray       # the tray (Linux needs GTK 3 and libayatana-appindicator)
-tsunagi network broadcast games off
-tsunagi network broadcast games on
 ```
 
-The choice persists across restarts and a plain `join`. It can be changed while
+Windows needs [Wintun](https://www.wintun.net) next to `tsng.exe`.
-the agent runs; `status` shows it for each network. While broadcast is on, the
+Per-platform notes: [Linux](dist/linux/README.md), [Arch](dist/arch/README.md),
-agent routes `255.255.255.255` through the Tsunagi interface and allows inbound
+[macOS](dist/macos/README.md), [Windows](dist/windows/README.md).
-UDP from the overlay range on it (Linux and Windows, needs the same privilege as
-the interface), and removes both when it is turned off or the agent stops. Games
-bound to a physical address still bypass it. Physical LAN capture/subnet sharing
-is not implemented.
-See [broadcast.md](docs/broadcast.md) for domain isolation and future LAN gateways.
 
-## How peers find each other
+## How it works
 
-Two different lookups are involved, and only one of them is this project's:
+- Your name and secret derive a network identity. Members publish signed
+  contact records to the public Mainline DHT under it, and find each other there.
+- Every connection proves knowledge of the secret before it's accepted.
+  Traffic between members is end-to-end encrypted, relays included.
+- Addresses and names are claimed with each device's own key and replicated
+  between members. There is no one in charge, so nothing to be taken down.
 
-**1. Resolving one endpoint's address — iroh's, and it works today.**
+The secret is the only key, so make it a good one (the generated ones are).
-With `--reach relay` or `--reach direct`, iroh publishes a signed
+The [threat model](docs/threat-model.md) says what this does and doesn't protect against.
-record of this endpoint's addresses, keyed by its endpoint id, to the public
-service run by Number 0 — "n0", the company behind iroh — at `dns.iroh.link`,
-over pkarr and DNS, and resolves other endpoints the same way. That is why `--peer <endpoint-id>` works with no address attached:
-iroh looks it up. None of that code is ours.
-
-**2. Finding who is in a network — Mainline DHT by default.**
-`NetworkDiscovery` supplies unverified candidates. The Mainline backend uses
-a signing key derived from the network name and secret to publish signed
-BEP44 records containing each writer's endpoint ID and addresses. Its 16
-slots provide starting candidates, not a complete membership list or a limit
-on network size. After the first authenticated connection, introductions and
-signed state reveal the other members. `StaticBootstrap` (`--peer`) remains
-available, and tests use either a local Mainline Testnet or in-memory discovery.
-
-What this means in practice:
-
-- With `relay` or `direct`, **your endpoint id and IP addresses are published
-  to a public third-party service** (Number 0's, unless you change it). They are not secret, and the network secret is
-  never published, but an observer of that service learns that your endpoint
-  exists and where it is. `--reach local` publishes nothing.
-- With DHT enabled, endpoint records are also published to the public Mainline
-  DHT. They are signed, not encrypted; membership still requires the secret.
-- A relay, when one is needed, sees the volume and timing of your traffic — not
-  its contents. The default relays are Number 0's, in the US, EU and
-  Asia-Pacific.
-
-## Storage
-
-Two physically separate SQLite files, placed wherever the library's
-configuration says (`StoragePaths`). A future system service supplies its own
-paths; tests always use temporary directories.
-
-| file           | holds                                            | when damaged            |
-|----------------|--------------------------------------------------|-------------------------|
-| `state.sqlite` | device identity, network configuration, hostname | clear error, never reset |
-| `cache.sqlite` | address hints and other recoverable data          | discarded and recreated  |
-
-The `wg-quic` protocol keeps its own keys in its own store under `wg-quic/`,
-because a protocol's keys are neither the iroh identity nor the network
-secret.
-
-The command line agent puts everything under the platform's per-user
-directories by default; `--state-dir` and `--cache-dir` override them.
-
-One state directory belongs to one live agent, enforced with a real OS file
-lock rather than an existence check. That directory *is* the identity: one
-agent, one device key, one interface, and as many networks as you like on it
-— `tsunagi network join` adds them to the agent that is already running,
-which is why a second `tsunagi up` on the same directory is refused rather
-than made to work. A second agent on the same host is a second identity, and
-needs everything of its own: its own state and cache directories, its own
-interface name and its own overlay range. The library owns no globals, so
-several of them run side by side in one process as readily as in one host.
-
-### Leaving, and starting over
-
-Membership outlives a session, so it also has to be possible to end it.
-
-```bash
-tsunagi network                     # what this device belongs to
-tsunagi network leave lab           # give up the address and the name, then forget it
-tsunagi wipe --yes                  # remove everything and be a stranger again
-```
-
-**Stopping is not leaving.** `stop` closes this network's sessions, takes
-its address off the interface and keeps it from starting again, and that is
-all: the configuration, the secret, the signed state and the protocol key
-stay exactly as they are, nothing is announced, and to the others this
-device is simply away — an ordinary condition they already handle, with its
-address and name still reserved for it. `start` picks it up where it left
-off. A network named on the `up` command line is started by that command
-whatever its stored state, and the start-up banner says so rather than
-letting a `stop` quietly come back.
-
-`leave` is the other one, and it removes, locally: the configuration and
-the secret, this network's signed records, its cached address hints and the
-protocol key it used there. What it keeps is this author's version counter
-for that network — a rejoin has to continue above the release, or every
-replica would treat the new claim as stale. Everything about *other*
-networks, and the device identity itself, is untouched.
-
-`leave` publishes a signed `Release` **first**, while the agent is running and
-its sessions are up, so the address and the name are freed for the others
-instead of staying reserved to a member that has gone. They pass the tombstone
-on, so a member that was away hears it from them. With no agent running,
-nothing can sign or send it: the command says so and refuses, and `--offline`
-drops the network locally while leaving the others holding the old claim. The
-protocol key for that network goes too — rejoining is joining, not resuming.
-
-`leave`, `stop`, `start`, `secret` and `broadcast` accept an exact stored network
-name, its full id, or a unique id prefix (including a copied report ellipsis).
-Names are case-sensitive. If several networks share a name, or a name matches
-another network's id prefix, the command lists matching names and full ids and
-changes nothing. Use a full id to choose explicitly; a full id always takes
-precedence over a name. No secret is needed to select a configured network.
-
-`wipe` removes both directories' contents: the device identity, every network,
-every signed record and everything a protocol kept beside them. It refuses
-while an agent is running, and refuses a directory with no `state.sqlite` in
-it, so a mistyped `--state-dir` cannot take somebody's documents with it.
-Without `--yes` it only says what it would remove. It is not a goodbye: nobody
-is told, because after it there is no key left to sign anything with. Leave the
-networks first if the addresses should be freed.
 
 ## Documentation
 
-- [docs/architecture.md](docs/architecture.md) — module boundaries and runtime.
+[Architecture](docs/architecture.md) ·
-- [docs/wireguard.md](docs/wireguard.md) — the WireGuard plugin: overlay
+[Protocol](docs/protocol.md) ·
-  addressing, announcements, backends, reconciliation.
+[WireGuard data plane](docs/wireguard.md) ·
-- [docs/protocol.md](docs/protocol.md) — identity derivation, framing, handshake.
+[Routing](docs/routing.md) ·
-- [docs/sync-model.md](docs/sync-model.md) — the planned signed-state model and
+[Exit nodes](docs/exit-node.md) ·
-  what is deliberately not built yet.
+[Threat model](docs/threat-model.md) ·
-- [docs/threat-model.md](docs/threat-model.md) — threat model and known limits.
+[Contributing](AGENTS.md)
-- [docs/testing.md](docs/testing.md) — what the suite covers and what it does not.
-- [AGENTS.md](AGENTS.md) — rules for anyone (human or agent) changing this repo.
-
-## Security in one paragraph
-
-Membership is proved by an HMAC over a transcript keyed by a value derived from
-the shared secret, bound to the specific iroh connection through the TLS
-exporter, to the network id, to both endpoint identities and to distinct role
-labels. This targets high-entropy secrets: there is no PAKE here, so a short
-human passphrase is guessable offline by anyone who can reach the handshake.
-Anyone who knows the secret is a full participant and can create many
-identities. Read [docs/threat-model.md](docs/threat-model.md) before relying on
-any of this.
 
 ## Licence
 
-MIT OR Apache-2.0.
+[WTFPL](LICENSE): do what the fuck you want to.

crates/tsunagi-cli/Cargo.toml

@@ -1,47 +0,0 @@
-[package]
-name = "tsunagi-cli"
-version = "0.1.0"
-description = "The tsunagi command line agent."
-edition.workspace = true
-rust-version.workspace = true
-license.workspace = true
-repository.workspace = true
-
-[[bin]]
-name = "tsunagi"
-path = "src/main.rs"
-# The binary and the library share a name, which `cargo doc` cannot map to
-# two directories. The command line is documented by `--help`, not rustdoc,
-# so the library keeps the name and this opts out.
-doc = false
-
-[dependencies]
-tsunagi = { path = "../tsunagi", version = "0.1.0", features = ["tun-device", "dns-publish"] }
-tsunagi-wireguard = { path = "../tsunagi-wireguard", version = "0.1.0" }
-tsunagi-wg-quic = { path = "../tsunagi-wg-quic", version = "0.1.0" }
-tsunagi-tcp-tls = { path = "../tsunagi-tcp-tls", version = "0.1.0" }
-iroh.workspace = true
-tokio = { version = "1.53", features = ["rt", "rt-multi-thread", "sync", "time", "macros", "signal"] }
-tracing.workspace = true
-tracing-subscriber.workspace = true
-clap = { version = "4.5", features = ["derive", "env"] }
-# Already in the tree through clap. `anstream` strips the escapes when stdout
-# is not a terminal and turns on virtual terminal processing on Windows, so
-# colour is never written where it would show up as rubbish.
-anstream = "1.0"
-anstyle = "1.0"
-# Local interface addresses, for the diagnostics in `status`.
-netwatch = "0.19.3"
-
-# Resolving a group name to its gid for `up --control-group`, through a safe
-# wrapper (no unsafe of our own). Unix only.
-[target.'cfg(unix)'.dependencies]
-nix = { version = "0.31", features = ["user"] }
-
-[dev-dependencies]
-tokio = { version = "1.53", features = ["rt", "rt-multi-thread", "sync", "time", "macros", "process"] }
-tempfile.workspace = true
-simple-dns = "0.12"
-
-[lints]
-workspace = true

crates/tsunagi-cli/tests/identity.rs

@@ -1,56 +0,0 @@
-//! What the command line says about this device, against a running agent.
-//!
-//! These drive the real binary, which is why they live beside it rather
-//! than with the library's own tests: the library cannot depend on a binary
-//! built from a crate that depends on it.
-
-#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
-
-use tempfile::TempDir;
-use tsunagi::Agent;
-use tsunagi::config::{AgentConfig, StoragePaths, TransportPolicy};
-
-/// Asking who this device is must not need the directory lock.
-///
-/// The lock belongs to the one agent allowed to *write* the state. `id` only
-/// reads, so making it take the lock would mean the question could never be
-/// answered while an agent was running — which is exactly when you want to
-/// ask it.
-#[tokio::test]
-async fn identity_can_be_read_while_an_agent_holds_the_directory() {
-    let dir = TempDir::new().unwrap();
-
-    // Hold the directory the way a running agent does.
-    let agent = Agent::spawn(
-        AgentConfig::new(StoragePaths::under(dir.path()))
-            .with_transport(TransportPolicy::LocalOnly)
-            .with_loopback_bind(),
-    )
-    .await
-    .unwrap();
-    let expected = agent.endpoint_id().to_string();
-
-    let output = tokio::process::Command::new(env!("CARGO_BIN_EXE_tsunagi"))
-        .arg("id")
-        // The same layout `StoragePaths::under` gives the agent above.
-        .arg("--state-dir")
-        .arg(dir.path().join("state"))
-        .arg("--cache-dir")
-        .arg(dir.path().join("cache"))
-        .output()
-        .await
-        .unwrap();
-
-    let stdout = String::from_utf8_lossy(&output.stdout);
-    let stderr = String::from_utf8_lossy(&output.stderr);
-    assert!(
-        output.status.success(),
-        "`id` failed while an agent was running:\n{stderr}"
-    );
-    assert!(
-        stdout.contains(&expected),
-        "expected {expected} in:\n{stdout}"
-    );
-
-    agent.shutdown().await;
-}

crates/tsunagi-core/Cargo.toml

@@ -0,0 +1,113 @@
+[package]
+name = "tsunagi-core"
+version = "0.1.0"
+description = "Small private mesh networks: persistent agent identity, deterministic network spaces, an iroh control plane, signed state and a local DNS view."
+readme = "../../README.md"
+keywords = ["mesh", "p2p", "iroh", "networking"]
+categories = ["network-programming"]
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[lib]
+name = "tsunagi"
+
+[features]
+default = []
+# A real TUN device, so a plugin can carry actual IP traffic. On Linux it
+# needs CAP_NET_ADMIN; on Windows the process must run elevated and
+# `wintun.dll` must be reachable. Without either the in-memory device serves
+# tests. The platform-specific dependencies are declared per target, so
+# enabling this only pulls what the target it is built for actually uses.
+tun-device = [
+    "dep:tun",
+    "dep:rtnetlink",
+    "dep:caps",
+    "dep:futures-util",
+]
+# Telling the operating system where to send its DNS questions. systemd-resolved
+# on Linux, the Name Resolution Policy Table on Windows; the zone and the
+# server work without it either way.
+dns-publish = ["dep:zbus"]
+# The test harness in `testing`, for this crate's own tests and for a
+# protocol crate's. Not on by default: it is only of use to a test.
+testing = ["dep:tempfile", "dep:tracing-subscriber"]
+
+[dependencies]
+arc-swap = "1.9"
+iroh.workspace = true
+# `net` for the local control interface: a Unix socket on Unix, a named pipe
+# on Windows. Both live behind the same `net` feature.
+tokio = { workspace = true, features = ["net"] }
+tokio-stream = "0.1"
+serde.workspace = true
+postcard.workspace = true
+bytes.workspace = true
+thiserror.workspace = true
+tracing.workspace = true
+hex.workspace = true
+data-encoding.workspace = true
+rusqlite = { version = "0.40", features = ["bundled"] }
+hkdf = "0.13"
+hmac = "0.13"
+sha2 = "0.11"
+subtle = "2.6"
+zeroize = { version = "1.9", features = ["derive"] }
+rand = "0.10"
+# Already in the tree through iroh. A packet codec, not a DNS server: the
+# zone logic is ours and a full server framework would be a large dependency
+# for answering A records from memory.
+simple-dns = "0.12"
+# The IANA top-level domain list, compiled in: one function, no
+# dependencies, no network. Used only to warn that a zone name shadows a
+# real public domain, never to refuse one.
+tld = "2.40"
+fs4 = { version = "1.1", features = ["sync"] }
+directories = "6.0"
+# The real system hostname, without a libc call of our own: this crate is
+# forbidden `unsafe` and will not make one.
+gethostname = "1.1"
+netwatch = "0.19.3"
+netdev = "0.46"
+mainline = "8.0"
+futures-lite = "2.6"
+tun = { version = "0.8", features = ["async"], optional = true }
+# Only for the `testing` harness, which a protocol crate's tests use too.
+tempfile = { version = "3.24", optional = true }
+tracing-subscriber = { version = "0.3", features = ["env-filter"], optional = true }
+
+# Linux-only interface provisioning. `rtnetlink` configures the interface in
+# process, so no `ip` invocation is ever needed; `caps` keeps CAP_NET_ADMIN
+# out of the effective set except during the moments it is used.
+[target.'cfg(target_os = "linux")'.dependencies]
+rtnetlink = { version = "0.23", optional = true }
+# Pure Rust D-Bus, no libdbus to link against. `tokio` rather than the
+# default reactor, because the agent brings its own.
+zbus = { version = "5.19", default-features = false, features = ["tokio"], optional = true }
+caps = { version = "0.5", optional = true }
+futures-util = { version = "0.3", default-features = false, optional = true }
+
+# Windows-only interface provisioning. The Wintun adapter itself is created
+# and driven through the `tun` dependency, whose safe wrapper is the only way
+# in — loading `wintun.dll` is an `unsafe` call this crate forbids. `netdev`
+# (already in the tree through `netwatch`) reads the interface table through a
+# safe wrapper, which is how the provisioner observes an adapter by name
+# before deciding what to change. Creating an adapter needs the process to be
+# elevated and `wintun.dll` to be reachable at run time.
+[target.'cfg(target_os = "windows")'.dependencies]
+windows-sys = { version = "0.61", features = [
+    "Win32_Security",
+    "Win32_Security_Authorization",
+    "Win32_Foundation",
+] }
+
+[dev-dependencies]
+# Its own tests use the harness it publishes.
+tsunagi-core = { path = ".", features = ["testing"] }
+tokio = { version = "1.53", features = ["rt", "rt-multi-thread", "sync", "time", "macros", "process", "test-util"] }
+tempfile.workspace = true
+tracing-subscriber.workspace = true
+
+[lints]
+workspace = true

crates/tsunagi-core/src/agent/events.rs

@@ -129,6 +129,19 @@ pub enum Event {
         /// Why it is not up.
         reason: String,
     },
+    /// The name this agent claimed was claimed first by another member.
+    ///
+    /// Nothing stops working: this agent keeps its address and every
+    /// connection. It just is not found by that name until it is renamed or
+    /// the member that holds the name lets it go.
+    HostnameTaken {
+        /// The network.
+        network: NetworkId,
+        /// The name that is taken.
+        name: String,
+        /// The member that holds it.
+        holder: EndpointId,
+    },
     /// An IP plugin reported an error. Never fatal.
     PluginError {
         /// The network the call was scoped to.

crates/tsunagi-core/src/agent/mod.rs

@@ -26,8 +26,8 @@ mod status;
 
 pub use events::Event;
 pub use status::{
-    AgentStatus, CandidateStatus, MemberStatus, NetworkMetrics, NetworkState, NetworkStatus,
+    AgentStatus, CandidateStatus, DataPath, HostnameConflict, MemberStatus, NetworkMetrics,
-    OverlayStatus, PeerStatus,
+    NetworkState, NetworkStatus, OverlayStatus, PeerStatus,
 };
 
 use std::collections::HashMap;
@@ -388,6 +388,7 @@ impl Agent {
     async fn reserve_range(&self, network: NetworkId) -> RangePlan {
         let reserve = |wanted: Ipv4Range| {
             let reservation = crate::overlay::NetworkRoutes {
+                exit: Default::default(),
                 broadcast: Default::default(),
                 range: Some(wanted),
                 local: None,
@@ -581,7 +582,7 @@ impl Agent {
                         "`{name}` is already configured with a different secret, as {}. \
                          Joining with this one adds a second network under the same name; \
                          they share nothing. Check the secret, or use \
-                         `tsunagi network secret` \
+                         `tsng network secret` \
                          to see which is which.",
                         other.network_id
                     );
@@ -603,6 +604,72 @@ impl Agent {
         }
     }
 
+    /// Offers this agent as an exit node in a network, or stops, now and
+    /// after restart. Off unless somebody turns it on.
+    pub async fn set_exit_offer(&self, network_id: NetworkId, enabled: bool) -> Result<()> {
+        self.inner
+            .storage
+            .set_exit_node(network_id, enabled)
+            .await?;
+        if self.is_active(network_id).await {
+            let (reply, receive) = oneshot::channel();
+            self.command(network_id, NetCommand::SetExitOffer { enabled, reply })
+                .await?;
+            receive.await.map_err(|_| Error::Stopped)?;
+        }
+        Ok(())
+    }
+
+    /// Sends this device's internet traffic through a member of a network,
+    /// or back the ordinary way with `None`.
+    ///
+    /// A device has one default route, so choosing in one network clears the
+    /// choice in the others. The member has to be connected and offering
+    /// to be an exit node. Remembered across restarts.
+    pub async fn set_exit_via(&self, network_id: NetworkId, via: Option<EndpointId>) -> Result<()> {
+        let active = self.is_active(network_id).await;
+        if via.is_some() && !active {
+            return Err(Error::NetworkNotActive(network_id));
+        }
+        if active {
+            let (reply, receive) = oneshot::channel();
+            self.command(network_id, NetCommand::SetExitVia { via, reply })
+                .await?;
+            receive
+                .await
+                .map_err(|_| Error::Stopped)?
+                .map_err(|reason| Error::Rejected { reason })?;
+        }
+        self.inner
+            .storage
+            .set_exit_via(network_id, via.map(|peer| *peer.as_bytes()))
+            .await?;
+        if via.is_some() {
+            // One default route: whatever the other networks were doing, they
+            // are not any more.
+            let others: Vec<NetworkId> = self
+                .inner
+                .networks
+                .read()
+                .await
+                .keys()
+                .copied()
+                .filter(|other| *other != network_id)
+                .collect();
+            for other in others {
+                let (reply, receive) = oneshot::channel();
+                if self
+                    .command(other, NetCommand::SetExitVia { via: None, reply })
+                    .await
+                    .is_ok()
+                {
+                    let _ = receive.await;
+                }
+            }
+        }
+        Ok(())
+    }
+
     /// Changes a network's local broadcast policy now and after restart.
     pub async fn set_broadcast(&self, network_id: NetworkId, enabled: bool) -> Result<()> {
         self.inner
@@ -662,16 +729,23 @@ impl Agent {
                     as Arc<dyn crate::discovery::NetworkDiscovery>,
             )
         };
-        let broadcast = self
+        let stored = self
             .inner
             .storage
             .list_networks()
             .await?
             .into_iter()
-            .find(|stored| stored.network_id == network_id)
+            .find(|stored| stored.network_id == network_id);
-            .is_none_or(|stored| stored.broadcast);
+        let broadcast = stored.as_ref().is_none_or(|stored| stored.broadcast);
+        let exit_offer = stored.as_ref().is_some_and(|stored| stored.exit_node);
+        let exit_via = stored
+            .as_ref()
+            .and_then(|stored| stored.exit_via)
+            .and_then(|bytes| EndpointId::from_bytes(&bytes).ok());
         let handle = network::spawn(RuntimeParams {
             broadcast,
+            exit_offer,
+            exit_via,
             keys,
             adapter: self.inner.adapter.clone(),
             storage: self.inner.storage.clone(),
@@ -726,6 +800,11 @@ impl Agent {
         // itself stays, because the agent owns it and other networks may
         // still be using it.
         self.inner.routes.remove_network(network_id);
+        if let Some(interface) = self.inner.interface.get() {
+            interface
+                .set_underlay(network_id, Vec::new(), Vec::new())
+                .await;
+        }
         if let Some(interface) = self.inner.interface.get()
             && let Err(err) = interface.sync_addresses().await
         {
@@ -733,6 +812,7 @@ impl Agent {
         }
         if let Some(interface) = self.inner.interface.get() {
             interface.sync_broadcast_rules().await;
+            interface.sync_exit_rules().await;
         }
         self.inner.storage.set_auto_start(network_id, false).await?;
         Ok(())
@@ -886,6 +966,12 @@ impl Agent {
             let keys = NetworkKeys::derive(&stored.name, &stored.secret);
             networks.push(NetworkStatus {
                 broadcast: stored.broadcast,
+                exit_offer: stored.exit_node,
+                exit_via: stored
+                    .exit_via
+                    .and_then(|bytes| EndpointId::from_bytes(&bytes).ok()),
+                exit_via_online: false,
+                exit_rules: Default::default(),
                 descriptor: keys.descriptor(),
                 name: stored.name,
                 network_id: stored.network_id,
@@ -895,6 +981,7 @@ impl Agent {
                 // An inactive network has no runtime to ask; the roster and
                 // the range come from one. Empty, not invented.
                 members: Vec::new(),
+                hostname_conflict: None,
                 range: None,
                 range_conflict: None,
                 metrics: NetworkMetrics::default(),

crates/tsunagi-core/src/agent/network.rs

@@ -32,7 +32,8 @@ use super::events::Event;
 use super::session::{self, Session, SessionEvent};
 use super::shutdown::Shutdown;
 use super::status::{
-    CandidateStatus, MemberStatus, NetworkMetrics, NetworkState, NetworkStatus, PeerStatus,
+    CandidateStatus, DataPath, HostnameConflict, MemberStatus, NetworkMetrics, NetworkState,
+    NetworkStatus, PeerStatus,
 };
 
 /// An inbound connection that already passed the handshake.
@@ -66,6 +67,16 @@ pub(crate) enum NetCommand {
         enabled: bool,
         reply: oneshot::Sender<()>,
     },
+    /// Offer this agent as an exit node in this network, or stop.
+    SetExitOffer {
+        enabled: bool,
+        reply: oneshot::Sender<()>,
+    },
+    /// Send this device's internet traffic through a member, or stop.
+    SetExitVia {
+        via: Option<EndpointId>,
+        reply: oneshot::Sender<std::result::Result<(), String>>,
+    },
     /// Resend this agent's announcement to every peer of this network.
     Reannounce,
     /// Answer to a different name from now on.
@@ -106,6 +117,8 @@ impl std::fmt::Debug for NetCommand {
             NetCommand::Status { .. } => f.write_str("Status"),
             NetCommand::Recheck => f.write_str("Recheck"),
             NetCommand::SetBroadcast { enabled, .. } => write!(f, "SetBroadcast({enabled})"),
+            NetCommand::SetExitOffer { enabled, .. } => write!(f, "SetExitOffer({enabled})"),
+            NetCommand::SetExitVia { via, .. } => write!(f, "SetExitVia({})", via.is_some()),
             NetCommand::Reannounce => f.write_str("Reannounce"),
             NetCommand::SetHostname(_) => f.write_str("SetHostname"),
             NetCommand::Release { .. } => f.write_str("Release"),
@@ -137,6 +150,10 @@ impl NetworkHandle {
 /// Everything a network runtime needs to run.
 pub(crate) struct RuntimeParams {
     pub(crate) broadcast: bool,
+    /// This agent offers itself as an exit node here.
+    pub(crate) exit_offer: bool,
+    /// The member this device's internet traffic goes through.
+    pub(crate) exit_via: Option<EndpointId>,
     pub(crate) keys: NetworkKeys,
     pub(crate) adapter: EndpointAdapter,
     pub(crate) storage: Storage,
@@ -304,6 +321,10 @@ struct Runtime {
             std::time::Instant,
         ),
     >,
+    /// The protocols this agent last announced, in the order it announced
+    /// them. The order is its preference, and the lower of two ids settles
+    /// which protocol a pair runs.
+    local_capabilities: Vec<PluginCapability>,
     /// What this agent last told its peers it could reach, so it is only
     /// said again when it changed.
     announced_reach: HashSet<crate::proto::message::ReachableLink>,
@@ -322,6 +343,9 @@ struct Runtime {
     /// publish a claim afterwards — the periodic check, a peer's records
     /// arriving — would silently take it back.
     released: bool,
+    /// The name this agent last said was taken, so it is said once per
+    /// change rather than on every round.
+    reported_name_taken: Option<HostnameConflict>,
     /// The address last reported as absent from the interface, so it is said
     /// once rather than for ever.
     reported_missing: Option<std::net::Ipv4Addr>,
@@ -331,6 +355,14 @@ struct Runtime {
     pending_state: Vec<(EndpointId, Vec<SignedRecord>)>,
     /// The highest version this agent has ever published for this network.
     own_version: u64,
+    /// Whether the exit node in use was reachable when last looked at, so
+    /// that losing it is said once and getting it back is too.
+    exit_via_was_online: bool,
+    /// What the last announcement said about being an exit node.
+    announced_exit: bool,
+    /// The last hostname each peer announced, kept across restarts so a
+    /// member that is away can still be called by name.
+    known_hostnames: HashMap<EndpointId, String>,
 }
 
 impl Runtime {
@@ -342,6 +374,16 @@ impl Runtime {
         let (link_results_tx, link_results_rx) = mpsc::channel(64);
         let (candidate_tx, discovery_candidates) =
             mpsc::channel(params.limits.max_discovery_candidates.max(1));
+        let hub = crate::dataplane::relay::RelayHub::new(network_id, local_id);
+        // The order the protocols were configured in is also how links are
+        // preferred when a neighbour can be reached over more than one.
+        hub.set_priority(
+            params
+                .plugins
+                .iter()
+                .map(|plugin| plugin.protocol_id().to_string())
+                .collect(),
+        );
         let discovery_worker = params.discovery.as_ref().map(|backend| {
             DiscoveryWorker::spawn(
                 backend.clone(),
@@ -369,8 +411,9 @@ impl Runtime {
             dial_results_tx,
             dial_results_rx,
             links: HashMap::new(),
-            hub: crate::dataplane::relay::RelayHub::new(network_id, local_id),
+            hub,
             reachable: HashMap::new(),
+            local_capabilities: Vec::new(),
             announced_reach: HashSet::new(),
             opening: HashSet::new(),
             link_results_tx,
@@ -379,9 +422,13 @@ impl Runtime {
             reported_mismatch: HashSet::new(),
             released: false,
             reported_missing: None,
+            reported_name_taken: None,
             state: StateSet::new(),
             pending_state: Vec::new(),
             own_version: 0,
+            exit_via_was_online: false,
+            announced_exit: false,
+            known_hostnames: HashMap::new(),
         }
     }
 
@@ -501,6 +548,27 @@ impl Runtime {
                 self.reannounce();
                 let _ = reply.send(());
             }
+            NetCommand::SetExitOffer { enabled, reply } => {
+                self.params.exit_offer = enabled;
+                self.apply_exit().await;
+                self.reannounce();
+                let _ = reply.send(());
+            }
+            NetCommand::SetExitVia { via, reply } => {
+                let outcome = match via {
+                    Some(peer) if !self.exit_node_online(peer) => Err(
+                        "that member is not connected or does not offer to be an exit node"
+                            .to_string(),
+                    ),
+                    _ => Ok(()),
+                };
+                if outcome.is_ok() {
+                    self.params.exit_via = via;
+                    self.exit_via_was_online = via.is_some();
+                    self.apply_exit().await;
+                }
+                let _ = reply.send(outcome);
+            }
             NetCommand::Recheck => self.discovery_round().await,
             NetCommand::Reannounce => self.reannounce(),
             NetCommand::Release { reply } => {
@@ -569,6 +637,8 @@ impl Runtime {
                 tracing::debug!(%err, "could not queue re-announcement");
             }
         }
+        // What was announced decides which protocol each pair runs.
+        self.update_paths();
     }
 
     /// Queues a message without blocking the runtime loop.
@@ -621,6 +691,7 @@ impl Runtime {
         // alone, so something has to look again; this runs on a timer and
         // the check is a comparison when nothing has changed.
         self.ensure_own_claim().await;
+        self.report_hostname_taken();
         // The same timer repairs the relay picture: reachability is soft
         // state, repeated while it holds and forgotten when it stops.
         self.update_paths();
@@ -664,6 +735,34 @@ impl Runtime {
         self.start_dials();
         // Last, so it carries what this round learned.
         self.introduce_peers();
+        self.refresh_underlay().await;
+    }
+
+    /// Hands the interface the underlay destinations this network depends
+    /// on: the verified direct IPv4 paths of every control connection, and
+    /// the relays in use. Only hosts that cannot exempt the agent from an
+    /// exit node's default route read it.
+    async fn refresh_underlay(&self) {
+        let Some(interface) = self.params.interface.clone() else {
+            return;
+        };
+        let mut addresses = Vec::new();
+        let mut hosts = Vec::new();
+        for session in self.sessions.values() {
+            for path in snapshot_connection(&session.conn).paths {
+                match path.remote {
+                    PathAddr::Ip(std::net::SocketAddr::V4(socket)) => addresses.push(*socket.ip()),
+                    PathAddr::Relay(url) => hosts.extend(relay_host(&url)),
+                    _ => {}
+                }
+            }
+        }
+        for url in self.params.adapter.snapshot().relay_urls {
+            hosts.extend(relay_host(&url));
+        }
+        interface
+            .set_underlay(self.network_id, addresses, hosts)
+            .await;
     }
 
     fn add_candidate(&mut self, candidate: Candidate) {
@@ -844,6 +943,17 @@ impl Runtime {
             .own_record_version(self.network_id, self.local_id)
             .await
             .unwrap_or(0);
+        for (id, hostname) in self
+            .params
+            .storage
+            .peer_hostnames(self.network_id)
+            .await
+            .unwrap_or_default()
+        {
+            if let Ok(id) = EndpointId::from_bytes(&id) {
+                self.known_hostnames.insert(id, hostname);
+            }
+        }
 
         self.ensure_own_claim().await;
         self.publish_allocations().await;
@@ -944,12 +1054,25 @@ impl Runtime {
             }
         };
 
+        // A name keeps the time it was first claimed for as long as this
+        // member keeps the name, so a later claimant cannot overtake it by
+        // the passage of time, and a new or changed name starts the clock
+        // afresh.
+        let hostname_since = wanted_hostname.as_ref().map(|name| {
+            let kept = self
+                .state
+                .get(&self.local_id)
+                .filter(|record| record.body.hostname() == Some(name.as_str()))
+                .and_then(|record| record.body.hostname_since());
+            kept.unwrap_or_else(unix_millis)
+        });
         let body = RecordBody::Claim {
             address: wanted_address,
             // The range only travels with an address, so a member of an
             // IPv6-only network does not assert one.
             range: wanted_address.and(range),
             hostname: wanted_hostname,
+            hostname_since,
         };
 
         // Nothing to say is not the same as saying nothing changed: a member
@@ -1013,6 +1136,7 @@ impl Runtime {
         for (peer, records) in std::mem::take(&mut self.pending_state) {
             self.receive_state(peer, records).await;
         }
+        self.report_hostname_taken();
     }
 
     /// Sends everything we know to every peer.
@@ -1095,6 +1219,75 @@ impl Runtime {
         }
     }
 
+    fn exit_policy(&self) -> crate::overlay::ExitPolicy {
+        crate::overlay::ExitPolicy {
+            offer: self.params.exit_offer,
+            via: self.params.exit_via,
+        }
+    }
+
+    /// Whether this agent offers to be an exit node and can really be one.
+    fn exit_ready(&self) -> bool {
+        self.params.exit_offer
+            && self
+                .params
+                .interface
+                .as_ref()
+                .is_some_and(|interface| interface.exit_offer_ready(self.network_id))
+    }
+
+    /// Whether a member is connected and says it is an exit node.
+    fn exit_node_online(&self, peer: EndpointId) -> bool {
+        self.sessions
+            .get(&peer)
+            .is_some_and(|session| session.exit_node)
+    }
+
+    /// Puts the exit settings into the routing table and the host rules.
+    ///
+    /// The routes and the rules stay as they are when the exit node in use
+    /// goes away: dropping them would send the traffic out the old way, in
+    /// the clear, without anyone having asked.
+    async fn apply_exit(&mut self) {
+        self.params
+            .routes
+            .set_exit(self.network_id, self.exit_policy());
+        if let Some(interface) = self.params.interface.clone() {
+            interface.sync_exit_rules().await;
+        }
+        // Said only once it is true: the rules may not have taken, or may
+        // only now be possible.
+        if self.exit_ready() != self.announced_exit {
+            self.reannounce();
+        }
+    }
+
+    /// Says so, once, when the exit node in use is lost or comes back.
+    fn watch_exit_via(&mut self) {
+        let Some(via) = self.params.exit_via else {
+            return;
+        };
+        let online = self.exit_node_online(via);
+        if online == self.exit_via_was_online {
+            return;
+        }
+        self.exit_via_was_online = online;
+        if online {
+            tracing::info!(
+                network = %self.network_id,
+                exit_node = %via.fmt_short(),
+                "the exit node is back"
+            );
+        } else {
+            tracing::warn!(
+                network = %self.network_id,
+                exit_node = %via.fmt_short(),
+                "the exit node is gone or no longer offers to be one; internet traffic stays \
+                 routed through it and is dropped until it returns or `tsng exit-node off`"
+            );
+        }
+    }
+
     fn update_broadcast(&self) {
         self.params
             .routes
@@ -1123,6 +1316,7 @@ impl Runtime {
         // a packet for ourselves does not go over a tunnel.
         let local = self.state.address_of(&self.local_id);
         let routes = crate::overlay::NetworkRoutes {
+            exit: self.exit_policy(),
             broadcast: self.broadcast_policy(),
             range: Some(range),
             local,
@@ -1219,6 +1413,7 @@ impl Runtime {
         // only once the address is really on the interface.
         if !is_missing {
             interface.sync_broadcast_rules().await;
+            self.apply_exit().await;
         }
     }
 
@@ -1500,68 +1695,93 @@ impl Runtime {
         }
     }
 
+    /// The protocol this agent and a member run their tunnel in, if they have
+    /// one in common.
+    ///
+    /// Both ends must name the same one without asking each other, and what
+    /// each side was configured to prefer can differ. So the member with the
+    /// lower id decides, by the order it announces its protocols in, and the
+    /// other side reads that order from the announcement it already has.
+    fn tunnel_protocol(&self, session: &Session) -> Option<String> {
+        let usable = |ours: &[PluginCapability], theirs: &[PluginCapability], name: &str| {
+            ours.iter().any(|capability| {
+                capability.enabled
+                    && capability.protocol == name
+                    && theirs.iter().any(|other| {
+                        other.enabled
+                            && other.protocol == name
+                            && other.version == capability.version
+                    })
+            })
+        };
+        let (decides, other) = if self.local_id.as_bytes() < session.peer.as_bytes() {
+            (&self.local_capabilities, &session.capabilities)
+        } else {
+            (&session.capabilities, &self.local_capabilities)
+        };
+        decides
+            .iter()
+            .find(|capability| usable(decides, other, &capability.protocol))
+            .map(|capability| capability.protocol.clone())
+    }
+
     /// Builds the graph off the packet path. Every remote row comes from that
-    /// member's authenticated control session; stale or incompatible rows never
+    /// member's authenticated control session, and a row says only who that
-    /// enter the graph. The hub replaces an immutable table only on changes.
+    /// member has a link to, never what kind of link: a member in the middle
+    /// needs no protocol in common with either end. Stale rows never enter the
+    /// graph. The hub replaces an immutable table only on changes.
     fn update_paths(&mut self) {
         self.reachable.retain(|peer, (_, heard)| {
             heard.elapsed() < REACH_EXPIRY && self.sessions.contains_key(peer)
         });
-        for (protocol, version) in self.served_protocols() {
+        let mut members: HashSet<_> = self.sessions.keys().map(|peer| *peer.as_bytes()).collect();
-            let peers: Vec<_> = self
+        members.insert(*self.local_id.as_bytes());
-                .sessions
+        let graph = self
-                .values()
+            .reachable
-                .filter(|session| {
+            .iter()
-                    session.capabilities.iter().any(|capability| {
+            .filter(|(peer, _)| members.contains(peer.as_bytes()))
-                        capability.enabled
+            .map(|(peer, (links, _))| {
-                            && capability.protocol == protocol
+                let mut neighbors: Vec<_> = links
-                            && capability.version == version
-                    })
-                })
-                .map(|session| session.peer)
-                .collect();
-            let mut members: HashSet<_> = peers.iter().map(|peer| *peer.as_bytes()).collect();
-            members.insert(*self.local_id.as_bytes());
-            let graph = self
-                .reachable
-                .iter()
-                .filter(|(peer, _)| members.contains(peer.as_bytes()))
-                .map(|(peer, (links, _))| {
-                    let mut neighbors: Vec<_> = links
-                        .iter()
-                        .filter(|link| {
-                            link.protocol == protocol
-                                && members.contains(&link.peer)
-                                && link.peer != *peer.as_bytes()
-                        })
-                        .map(|link| link.peer)
-                        .collect();
-                    neighbors.sort_unstable();
-                    (*peer.as_bytes(), neighbors)
-                })
-                .collect();
-            self.hub.set_topology(&protocol, graph, members);
-            for peer in peers {
-                if self.hub.has_link(peer, &protocol) || !self.hub.reachable(peer, &protocol) {
-                    continue;
-                }
-                let Some(plugin) = self
-                    .params
-                    .plugins
                     .iter()
-                    .find(|plugin| plugin.protocol_id() == protocol)
+                    .filter(|link| members.contains(&link.peer) && link.peer != *peer.as_bytes())
-                    .cloned()
+                    .map(|link| link.peer)
-                else {
+                    .collect();
-                    continue;
+                neighbors.sort_unstable();
-                };
+                neighbors.dedup();
-                let link = self.hub.link(peer, &protocol);
+                (*peer.as_bytes(), neighbors)
-                let path = link.path_description();
+            })
-                let max_datagram = link.max_datagram_size();
+            .collect();
-                plugin.on_peer_link(self.network_id, peer, link);
+        self.hub.set_topology(graph, members);
+
+        let wanted: Vec<(EndpointId, String)> = self
+            .sessions
+            .values()
+            .filter_map(|session| Some((session.peer, self.tunnel_protocol(session)?)))
+            .collect();
+        for (peer, protocol) in wanted {
+            if self.hub.has_link(peer, &protocol) || !self.hub.reachable(peer) {
+                continue;
+            }
+            let Some(plugin) = self
+                .params
+                .plugins
+                .iter()
+                .find(|plugin| plugin.protocol_id() == protocol)
+                .cloned()
+            else {
+                continue;
+            };
+            let link = self.hub.link(peer, &protocol);
+            let relayed = self.hub.route(peer).is_some_and(|route| route.hops > 1);
+            let path = link.path_description();
+            let max_datagram = link.max_datagram_size();
+            plugin.on_peer_link(self.network_id, peer, link);
+            // A direct link has already been reported as one.
+            if relayed {
                 self.emit(Event::DataLinkUp {
                     network: self.network_id,
                     peer,
-                    protocol: protocol.clone(),
+                    protocol,
                     path,
                     max_datagram,
                 });
@@ -1628,30 +1848,25 @@ impl Runtime {
 
     /// Hands a link to the plugin that owns its protocol.
     fn adopt_link(&mut self, peer: EndpointId, protocol: String, link: SharedLink) {
-        let Some(plugin) = self
+        if !self
             .params
             .plugins
             .iter()
-            .find(|plugin| plugin.protocol_id() == protocol)
+            .any(|plugin| plugin.protocol_id() == protocol)
-            .cloned()
+        {
-        else {
             return;
-        };
+        }
 
         let path = link.path_description();
+        let max_datagram = link.max_datagram_size();
         self.links
             .insert((peer, protocol.clone()), Arc::clone(&link));
-        // The protocol is handed the hub's link, not this one: the same
+        // What this is, is a way to reach the peer. Which protocol's
-        // object for as long as the peer is a peer, whatever happens to
+        // tunnel runs over it is decided in `update_paths`, and that tunnel
-        // the path under it. A tunnel is not torn down because a direct
+        // is handed the hub's link, not this one: the same object for as
-        // link came or went.
+        // long as the peer is a peer, whatever happens to the path under
-        let first_time = !self.hub.has_link(peer, &protocol);
+        // it. A tunnel is not torn down because a direct link came or went.
         self.hub.set_direct(peer, &protocol, link);
-        let shared = self.hub.link(peer, &protocol);
-        let max_datagram = shared.max_datagram_size();
-        if first_time {
-            plugin.on_peer_link(self.network_id, peer, shared);
-        }
         self.metrics.data_links_established += 1;
         self.emit(Event::DataLinkUp {
             network: self.network_id,
@@ -1783,8 +1998,18 @@ impl Runtime {
             });
         }
         capabilities.truncate(self.params.limits.max_capabilities);
+        self.local_capabilities = capabilities
+            .iter()
+            .map(|capability| PluginCapability {
+                data: Vec::new(),
+                ..capability.clone()
+            })
+            .collect();
+        let exit_node = self.exit_ready();
+        self.announced_exit = exit_node;
         Announcement {
             broadcast: self.params.broadcast,
+            exit_node,
             hostname: self.params.hostname.clone(),
             capabilities,
         }
@@ -1863,6 +2088,7 @@ impl Runtime {
                 self.metrics.disconnects += 1;
                 self.drop_links_for(peer);
                 self.update_broadcast();
+                self.watch_exit_via();
                 self.update_paths();
                 self.announce_reach(false);
                 for plugin in &self.params.plugins {
@@ -1885,6 +2111,33 @@ impl Runtime {
         }
     }
 
+    /// Keeps the name a peer announced, on disk too when it changed.
+    ///
+    /// Written off the loop: a name that is not stored this time is stored
+    /// the next time the peer announces it.
+    fn remember_hostname(&mut self, peer: EndpointId, hostname: &str) {
+        if hostname.is_empty()
+            || self
+                .known_hostnames
+                .get(&peer)
+                .is_some_and(|h| h == hostname)
+        {
+            return;
+        }
+        self.known_hostnames.insert(peer, hostname.to_string());
+        let storage = self.params.storage.clone();
+        let network_id = self.network_id;
+        let hostname = hostname.to_string();
+        tokio::spawn(async move {
+            if let Err(err) = storage
+                .remember_peer_hostname(network_id, *peer.as_bytes(), hostname)
+                .await
+            {
+                tracing::debug!(%err, "could not remember a peer's hostname");
+            }
+        });
+    }
+
     fn dispatch_message(&mut self, peer: EndpointId, message: ControlMessage) {
         match &message {
             ControlMessage::Announce(announcement) => {
@@ -1892,9 +2145,12 @@ impl Runtime {
                 if let Some(session) = self.sessions.get_mut(&peer) {
                     session.hostname = Some(announcement.hostname.clone());
                     session.broadcast = announcement.broadcast;
+                    session.exit_node = announcement.exit_node;
                     session.capabilities = capabilities.clone();
                 }
+                self.remember_hostname(peer, &announcement.hostname);
                 self.update_broadcast();
+                self.watch_exit_via();
                 self.dispatch_capabilities(peer, &capabilities);
                 self.ensure_links();
                 self.update_paths();
@@ -1983,6 +2239,69 @@ impl Runtime {
 
     // ----------------------------------------------------------------- status
 
+    /// Whether a member can be reached now, by any path.
+    ///
+    /// The single definition every client reports: a live control session,
+    /// or a data path to it through other members. Being reached over a long
+    /// path is being online; how well is `data_path`'s to say.
+    fn is_online(&self, peer: EndpointId) -> bool {
+        peer == self.local_id || self.sessions.contains_key(&peer) || self.hub.reachable(peer)
+    }
+
+    /// How packets reach a member, which says nothing about whether it is
+    /// there.
+    fn data_path(&self, peer: EndpointId) -> DataPath {
+        match self.hub.route(peer) {
+            None => DataPath::None,
+            Some(route) if route.hops <= 1 => DataPath::Direct {
+                transport: self
+                    .hub
+                    .direct_kinds(peer)
+                    .into_iter()
+                    .next()
+                    .unwrap_or_default(),
+            },
+            Some(route) => DataPath::Relayed {
+                hops: route.hops,
+                via: route.via,
+            },
+        }
+    }
+
+    /// Says so when this agent's own name is held by someone else, and
+    /// again if that changes. Never anything but a statement: the agent keeps
+    /// working by address either way.
+    fn report_hostname_taken(&mut self) {
+        let taken = self.hostname_conflict_of(&self.local_id);
+        if taken == self.reported_name_taken {
+            return;
+        }
+        if let Some(conflict) = &taken {
+            tracing::warn!(
+                network = %self.network_id,
+                name = %conflict.name,
+                holder = %conflict.holder.fmt_short(),
+                "this name was claimed first by another member; it stays reachable by \
+                 address but is not found by this name until it is renamed"
+            );
+            self.emit(Event::HostnameTaken {
+                network: self.network_id,
+                name: conflict.name.clone(),
+                holder: conflict.holder,
+            });
+        }
+        self.reported_name_taken = taken;
+    }
+
+    fn hostname_conflict_of(&self, author: &EndpointId) -> Option<HostnameConflict> {
+        self.state
+            .hostname_taken(author)
+            .map(|(name, holder)| HostnameConflict {
+                name: name.to_string(),
+                holder,
+            })
+    }
+
     fn status(&self) -> NetworkStatus {
         let served = self.served_protocols();
         let mut peers: Vec<PeerStatus> = self
@@ -1992,9 +2311,13 @@ impl Runtime {
                 let snapshot = snapshot_connection(&session.conn);
                 PeerStatus {
                     broadcast: session.broadcast,
+                    exit_node: session.exit_node,
                     endpoint_id: session.peer,
                     role: session.role,
-                    hostname: session.hostname.clone(),
+                    hostname: session
+                        .hostname
+                        .clone()
+                        .or_else(|| self.known_hostnames.get(&session.peer).cloned()),
                     protocols: session
                         .capabilities
                         .iter()
@@ -2016,6 +2339,7 @@ impl Runtime {
                     control_messages_received: session.messages_received,
                     control_bytes_sent: session.bytes_sent,
                     control_bytes_received: session.bytes_received,
+                    data_path: self.data_path(session.peer),
                 }
             })
             .collect();
@@ -2052,6 +2376,10 @@ impl Runtime {
                     // both hold it would be untrue on one of them.
                     overlay_address_v4: self.state.address_of(&endpoint_id),
                     hostname: self.state.hostname_of(&endpoint_id).map(str::to_string),
+                    last_hostname: self.known_hostnames.get(&endpoint_id).cloned(),
+                    hostname_conflict: self.hostname_conflict_of(&endpoint_id),
+                    online: self.is_online(endpoint_id),
+                    data_path: self.data_path(endpoint_id),
                 })
             })
             .collect();
@@ -2060,6 +2388,18 @@ impl Runtime {
 
         NetworkStatus {
             broadcast: self.params.broadcast,
+            exit_offer: self.params.exit_offer,
+            exit_via: self.params.exit_via,
+            exit_via_online: self
+                .params
+                .exit_via
+                .is_some_and(|via| self.exit_node_online(via)),
+            exit_rules: self
+                .params
+                .interface
+                .as_ref()
+                .map(|interface| interface.exit_rules(self.network_id))
+                .unwrap_or_default(),
             descriptor: self.params.keys.descriptor(),
             name: self.params.keys.name().clone(),
             network_id: self.network_id,
@@ -2067,6 +2407,7 @@ impl Runtime {
             peers,
             candidates,
             members,
+            hostname_conflict: self.hostname_conflict_of(&self.local_id),
             range: self.effective_range(),
             // Only worth reporting while it is actually stuck: with a
             // fallback in play the configured range being another
@@ -2081,6 +2422,15 @@ impl Runtime {
     }
 }
 
+/// Milliseconds since the Unix epoch, for the time a name was first claimed.
+fn unix_millis() -> u64 {
+    std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map_or(u64::MAX, |elapsed| {
+            u64::try_from(elapsed.as_millis()).unwrap_or(u64::MAX)
+        })
+}
+
 /// Which side dialled, given a role and the two identities.
 fn initiator_of(role: Role, local: EndpointId, peer: EndpointId) -> EndpointId {
     match role {
@@ -2267,3 +2617,48 @@ mod tests {
         assert_eq!(chosen_restored.copied(), Some("wg"));
     }
 }
+
+/// The host name of a relay URL such as `https://relay.example:443/`.
+fn relay_host(url: &str) -> Option<String> {
+    let rest = url.split_once("://").map_or(url, |(_, rest)| rest);
+    let authority = rest.split(['/', '?', '#']).next()?;
+    let host = authority.rsplit_once('@').map_or(authority, |(_, h)| h);
+    let host = if host.starts_with('[') {
+        host.split_once(']')?.0.trim_start_matches('[')
+    } else {
+        host.split(':').next()?
+    };
+    (!host.is_empty()
+        && host.len() <= 253
+        && host
+            .chars()
+            .all(|c| c.is_ascii_alphanumeric() || c == '.' || c == '-' || c == ':'))
+    .then(|| host.to_ascii_lowercase())
+}
+
+#[cfg(test)]
+mod relay_host_tests {
+    use super::relay_host;
+
+    #[test]
+    fn the_host_is_taken_out_of_a_relay_url() {
+        assert_eq!(
+            relay_host("https://relay.example.com./").as_deref(),
+            Some("relay.example.com.")
+        );
+        assert_eq!(
+            relay_host("https://Euw1-1.relay.iroh.network:443/x").as_deref(),
+            Some("euw1-1.relay.iroh.network")
+        );
+        assert_eq!(
+            relay_host("http://192.0.2.7:3340").as_deref(),
+            Some("192.0.2.7")
+        );
+        assert_eq!(
+            relay_host("https://[2001:db8::1]:443/").as_deref(),
+            Some("2001:db8::1")
+        );
+        assert_eq!(relay_host("https:///").as_deref(), None);
+        assert_eq!(relay_host("https://bad host/").as_deref(), None);
+    }
+}

crates/tsunagi-core/src/agent/session.rs

@@ -74,6 +74,8 @@ pub(crate) struct Session {
     pub(crate) hostname: Option<String>,
     pub(crate) capabilities: Vec<PluginCapability>,
     pub(crate) broadcast: bool,
+    /// The peer offers itself as an exit node in this network.
+    pub(crate) exit_node: bool,
     pub(crate) messages_sent: u64,
     pub(crate) messages_received: u64,
     pub(crate) bytes_sent: u64,
@@ -228,6 +230,7 @@ pub(crate) fn spawn(
         hostname: None,
         capabilities: Vec::new(),
         broadcast: false,
+        exit_node: false,
         messages_sent: 0,
         messages_received: 0,
         bytes_sent: 0,

crates/tsunagi-core/src/agent/status.rs

@@ -59,6 +59,43 @@ pub struct OverlayStatus {
     pub broadcast_rules: Option<crate::overlay::BroadcastRulesReport>,
 }
 
+/// How packets reach a member right now.
+///
+/// Being reachable is one thing and being reachable well is another, and
+/// the second is never a reason to call a member away: a member that can only
+/// be reached through somebody else is online, over a longer path.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum DataPath {
+    /// Nothing carries packets to it yet. The member is connected for
+    /// control only, which is the state of a data path being set up.
+    None,
+    /// A direct link, of the named kind of transport.
+    Direct {
+        /// The kind of transport carrying it, e.g. `wg`.
+        transport: String,
+    },
+    /// Through other members.
+    Relayed {
+        /// Number of links on the way, at least two.
+        hops: u8,
+        /// The member the first of them goes to.
+        via: EndpointId,
+    },
+}
+
+/// A name that a member claimed and somebody else holds.
+///
+/// A name belongs to whoever claimed it first. The member that claimed it
+/// later is still a member and still reachable by its address; it is just
+/// not found by that name, on any member of the network.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct HostnameConflict {
+    /// The name that is taken.
+    pub name: String,
+    /// The member that holds it.
+    pub holder: EndpointId,
+}
+
 /// A member the signed state knows about, connected or not.
 ///
 /// This is the durable roster: it comes from signed records, so a member that
@@ -80,6 +117,20 @@ pub struct MemberStatus {
     /// Signed, so it is still known while the member is away — which is what
     /// lets an absent member be named rather than shown as a bare id.
     pub hostname: Option<String>,
+    /// The last name this agent saw it announce, whether or not it is here.
+    ///
+    /// Not signed, so it is a convenience for naming a member that is away
+    /// and never a claim: the zone is served from `hostname`.
+    pub last_hostname: Option<String>,
+    /// The name it claimed, when somebody else claimed it first.
+    pub hostname_conflict: Option<HostnameConflict>,
+    /// Whether this agent can reach it now, by any path: a live control
+    /// session, or a data path through other members. The one answer to "is
+    /// it online" for every client, so that none of them has to work it out
+    /// from a different part of the picture. This agent counts as online.
+    pub online: bool,
+    /// How packets reach it. [`DataPath::None`] while it is offline.
+    pub data_path: DataPath,
 }
 
 /// Status of one authenticated session.
@@ -87,6 +138,8 @@ pub struct MemberStatus {
 pub struct PeerStatus {
     /// This authenticated peer accepts network broadcasts.
     pub broadcast: bool,
+    /// This authenticated peer offers itself as an exit node.
+    pub exit_node: bool,
     /// Authenticated endpoint id.
     pub endpoint_id: EndpointId,
     /// Which side this agent played in the handshake.
@@ -121,6 +174,8 @@ pub struct PeerStatus {
     pub control_bytes_sent: u64,
     /// Control payload bytes read from this session.
     pub control_bytes_received: u64,
+    /// How packets reach this peer right now.
+    pub data_path: DataPath,
 }
 
 /// Counters scoped to one logical network.
@@ -159,6 +214,14 @@ pub struct NetworkMetrics {
 pub struct NetworkStatus {
     /// Local broadcast participation in this network.
     pub broadcast: bool,
+    /// This agent offers itself as an exit node in this network.
+    pub exit_offer: bool,
+    /// The member this device sends all its internet traffic through.
+    pub exit_via: Option<EndpointId>,
+    /// Whether that member is connected and still offering to be one.
+    pub exit_via_online: bool,
+    /// What the host rules for the exit settings are doing.
+    pub exit_rules: crate::overlay::ExitRulesReport,
     /// Immutable deterministic description of the network space.
     pub descriptor: NetworkDescriptor,
     /// Network name, for convenience.
@@ -173,6 +236,10 @@ pub struct NetworkStatus {
     pub candidates: Vec<CandidateStatus>,
     /// Members the signed state knows about, whether connected or not.
     pub members: Vec<MemberStatus>,
+    /// This agent's own name, when another member claimed it first and so
+    /// holds it. This agent keeps working by address; nobody finds it by
+    /// this name until it is renamed or the other member lets it go.
+    pub hostname_conflict: Option<HostnameConflict>,
     /// The overlay range this network uses, once it has one.
     pub range: Option<crate::state::Ipv4Range>,
     /// The range it could not have, because another network on this agent

crates/tsunagi-core/src/dataplane/relay.rs

@@ -67,10 +67,41 @@ impl Tally {
     }
 }
 
+/// The links to one neighbour, best first. Which transport carries a frame
+/// is decided here and nowhere else: the end-to-end protocol is in the
+/// envelope and never depends on it.
 #[derive(Debug)]
 struct NextHop {
     peer: PeerId,
-    link: SharedLink,
+    links: Box<[SharedLink]>,
+}
+
+impl NextHop {
+    fn usable(&self) -> bool {
+        self.links.iter().any(|link| !link.is_closed())
+    }
+
+    fn first_open(&self) -> Option<&SharedLink> {
+        self.links.iter().find(|link| !link.is_closed())
+    }
+
+    /// Hands a frame to the best open link that accepts it. A link that
+    /// cannot carry the frame (too large for its path, closed a moment ago)
+    /// leaves it to the next one; the frame is only copied when there is
+    /// another to try.
+    fn send(&self, frame: Bytes) -> Result<(), TransportError> {
+        let mut open = self.links.iter().filter(|link| !link.is_closed());
+        let Some(mut current) = open.next() else {
+            return Err(TransportError::Closed);
+        };
+        for next in open {
+            if current.send(frame.clone()).is_ok() {
+                return Ok(());
+            }
+            current = next;
+        }
+        current.send(frame)
+    }
 }
 
 #[derive(Debug)]
@@ -82,21 +113,22 @@ struct ForwardRoute {
 impl ForwardRoute {
     fn select(&self, source: &PeerId, flow: FlowId) -> Option<&NextHop> {
         if self.next.len() == 1 {
-            return self.next.first().filter(|hop| !hop.link.is_closed());
+            return self.next.first().filter(|hop| hop.usable());
         }
         let seed = u64::from_le_bytes(source[..8].try_into().ok()?);
         let start = mix64(flow ^ seed) as usize % self.next.len();
         // Stable fallback if a link closed just before its table was replaced.
         (0..self.next.len())
             .map(|i| &self.next[(start + i) % self.next.len()])
-            .find(|hop| !hop.link.is_closed())
+            .find(|hop| hop.usable())
     }
 }
 
 #[derive(Debug, Default)]
 struct ForwardingTable {
     routes: HashMap<PeerId, ForwardRoute>,
-    inboxes: HashMap<PeerId, mpsc::Sender<Bytes>>,
+    /// Local delivery, by who sent it and which end-to-end protocol it is.
+    inboxes: HashMap<(PeerId, u64), mpsc::Sender<Bytes>>,
     members: HashSet<PeerId>,
 }
 
@@ -121,7 +153,7 @@ impl Plane {
             return;
         }
         if header.destination == self.local {
-            let Some(inbox) = table.inboxes.get(&header.source) else {
+            let Some(inbox) = table.inboxes.get(&(header.source, header.protocol)) else {
                 self.tally.dropped_unknown.fetch_add(1, Ordering::Relaxed);
                 return;
             };
@@ -144,7 +176,7 @@ impl Plane {
             self.tally.dropped_no_link.fetch_add(1, Ordering::Relaxed);
             return;
         };
-        if hop.link.send(envelope::decrement(frame)).is_ok() {
+        if hop.send(envelope::decrement(frame)).is_ok() {
             self.tally.forwarded.fetch_add(1, Ordering::Relaxed);
         } else {
             self.tally.dropped_no_link.fetch_add(1, Ordering::Relaxed);
@@ -152,27 +184,65 @@ impl Plane {
     }
 }
 
+/// One physical link to a neighbour, of whatever kind of transport.
 #[derive(Debug)]
-struct Protocol {
+struct RawLink {
-    plane: Arc<Plane>,
+    kind: String,
-    graph: HashMap<PeerId, Vec<PeerId>>,
+    link: SharedLink,
-    members: HashSet<PeerId>,
+    reader: JoinHandle<()>,
-    raw: HashMap<PeerId, SharedLink>,
-    readers: HashMap<PeerId, JoinHandle<()>>,
-    links: HashMap<PeerId, Arc<PeerLink>>,
 }
 
-impl Protocol {
+/// How a destination is reached right now.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct RouteSummary {
+    /// Number of transport links to it. One is a direct link.
+    pub hops: u8,
+    /// The neighbour the first link goes to. For a direct link that is the
+    /// destination itself.
+    pub via: EndpointId,
+}
+
+#[derive(Debug)]
+struct State {
+    plane: Arc<Plane>,
+    /// Transport kinds, best first. A neighbour with several links is
+    /// reached over the first of these it has.
+    priority: Vec<String>,
+    graph: HashMap<PeerId, Vec<PeerId>>,
+    members: HashSet<PeerId>,
+    raw: HashMap<PeerId, Vec<RawLink>>,
+    links: HashMap<(PeerId, String), Arc<PeerLink>>,
+}
+
+impl State {
+    fn rank(&self, kind: &str) -> usize {
+        self.priority
+            .iter()
+            .position(|known| known == kind)
+            .unwrap_or(usize::MAX)
+    }
+
+    /// A neighbour's links, best kind first.
+    fn ordered(&self, peer: &PeerId) -> Vec<&RawLink> {
+        let mut links: Vec<&RawLink> = self
+            .raw
+            .get(peer)
+            .map(|links| links.iter().collect())
+            .unwrap_or_default();
+        links.sort_by_key(|raw| (self.rank(&raw.kind), raw.kind.clone()));
+        links
+    }
+
     fn publish(&self) {
         let mut graph = self.graph.clone();
-        graph.insert(
+        let mut neighbours: Vec<PeerId> = self
-            self.plane.local,
+            .raw
-            self.raw
+            .iter()
-                .iter()
+            .filter(|(_, links)| links.iter().any(|raw| !raw.link.is_closed()))
-                .filter(|(_, link)| !link.is_closed())
+            .map(|(peer, _)| *peer)
-                .map(|(peer, _)| *peer)
+            .collect();
-                .collect(),
+        neighbours.sort_unstable();
-        );
+        graph.insert(self.plane.local, neighbours);
         let routing = RoutingTable::build(self.plane.local, &graph, ROUTING_HOP_LIMIT);
         let routes = routing
             .iter()
@@ -181,10 +251,12 @@ impl Protocol {
                     .next_hops
                     .iter()
                     .filter_map(|id| {
-                        self.raw.get(id).map(|link| NextHop {
+                        let links: Box<[_]> = self
-                            peer: *id,
+                            .ordered(id)
-                            link: link.clone(),
+                            .into_iter()
-                        })
+                            .map(|raw| raw.link.clone())
+                            .collect();
+                        (!links.is_empty()).then_some(NextHop { peer: *id, links })
                     })
                     .collect();
                 (!next.is_empty()).then_some((
@@ -204,17 +276,21 @@ impl Protocol {
             inboxes: self
                 .links
                 .iter()
-                .map(|(peer, link)| (*peer, link.inbox_tx.clone()))
+                .map(|((peer, _), link)| ((*peer, link.tag), link.inbox_tx.clone()))
                 .collect(),
         }));
     }
+
+    fn stop_readers(&mut self) {
+        for raw in self.raw.values().flatten() {
+            raw.reader.abort();
+        }
+    }
 }
 
-impl Drop for Protocol {
+impl Drop for State {
     fn drop(&mut self) {
-        for task in self.readers.values() {
+        self.stop_readers();
-            task.abort();
-        }
         for link in self.links.values() {
             link.close();
         }
@@ -222,12 +298,17 @@ impl Drop for Protocol {
     }
 }
 
-/// One network's transport links and independently published protocol tables.
+/// One network's transport links and its published forwarding table.
+///
+/// There is one table for the whole network, whatever protocols run over it.
+/// A link is a way to reach a neighbour; a protocol is an end-to-end channel
+/// to a peer. The two meet only in the envelope, which names the protocol, so
+/// a tunnel keeps working over any mix of transports and a middle member
+/// needs no protocol in common with either end.
 #[derive(Debug)]
 pub struct RelayHub {
     network: NetworkId,
-    local: PeerId,
+    state: Mutex<State>,
-    protocols: Mutex<HashMap<String, Protocol>>,
     tally: Arc<Tally>,
     changed: Arc<Notify>,
 }
@@ -235,40 +316,38 @@ pub struct RelayHub {
 impl RelayHub {
     /// Creates the router at this network's local endpoint.
     pub fn new(network: NetworkId, local: EndpointId) -> Arc<Self> {
+        let tally = Arc::new(Tally::default());
         Arc::new(Self {
             network,
-            local: *local.as_bytes(),
+            state: Mutex::new(State {
-            protocols: Mutex::default(),
+                plane: Arc::new(Plane {
-            tally: Arc::default(),
+                    local: *local.as_bytes(),
+                    table: ArcSwap::from_pointee(ForwardingTable::default()),
+                    tally: tally.clone(),
+                }),
+                priority: Vec::new(),
+                graph: HashMap::new(),
+                members: HashSet::new(),
+                raw: HashMap::new(),
+                links: HashMap::new(),
+            }),
+            tally,
             changed: Arc::default(),
         })
     }
 
-    fn protocols(&self) -> std::sync::MutexGuard<'_, HashMap<String, Protocol>> {
+    fn state(&self) -> std::sync::MutexGuard<'_, State> {
-        self.protocols
+        self.state.lock().unwrap_or_else(|error| error.into_inner())
-            .lock()
-            .unwrap_or_else(|error| error.into_inner())
     }
 
-    fn protocol<'a>(
+    /// Sets which kinds of transport are preferred, best first, when a
-        &self,
+    /// neighbour can be reached over more than one.
-        protocols: &'a mut HashMap<String, Protocol>,
+    pub fn set_priority(&self, kinds: Vec<String>) {
-        name: &str,
+        let mut state = self.state();
-    ) -> &'a mut Protocol {
+        if state.priority != kinds {
-        protocols
+            state.priority = kinds;
-            .entry(name.to_owned())
+            state.publish();
-            .or_insert_with(|| Protocol {
+        }
-                plane: Arc::new(Plane {
-                    local: self.local,
-                    table: ArcSwap::from_pointee(ForwardingTable::default()),
-                    tally: self.tally.clone(),
-                }),
-                graph: HashMap::new(),
-                members: HashSet::new(),
-                raw: HashMap::new(),
-                readers: HashMap::new(),
-                links: HashMap::new(),
-            })
     }
 
     /// Wakes the control loop promptly when a transport reader ends.
@@ -282,14 +361,11 @@ impl RelayHub {
     }
 
     /// Publishes authenticated topology. Refreshing identical state is cheap.
-    pub fn set_topology(
+    ///
-        &self,
+    /// Every row of `graph` is one member's own account of who it has a link
-        protocol: &str,
+    /// to; what kind of link it is does not matter here.
-        graph: HashMap<PeerId, Vec<PeerId>>,
+    pub fn set_topology(&self, graph: HashMap<PeerId, Vec<PeerId>>, members: HashSet<PeerId>) {
-        members: HashSet<PeerId>,
+        let mut state = self.state();
-    ) {
-        let mut protocols = self.protocols();
-        let state = self.protocol(&mut protocols, protocol);
         if state.graph != graph || state.members != members {
             state.graph = graph;
             state.members = members;
@@ -298,22 +374,44 @@ impl RelayHub {
     }
 
     /// Whether the current table has a path to this destination.
-    pub fn reachable(&self, peer: EndpointId, protocol: &str) -> bool {
+    pub fn reachable(&self, peer: EndpointId) -> bool {
-        self.protocols().get(protocol).is_some_and(|state| {
+        self.state()
-            state
+            .plane
-                .plane
+            .table
-                .table
+            .load()
-                .load()
+            .routes
-                .routes
+            .contains_key(peer.as_bytes())
-                .contains_key(peer.as_bytes())
+    }
+
+    /// How a destination is reached right now, if it is.
+    pub fn route(&self, peer: EndpointId) -> Option<RouteSummary> {
+        let table = self.state().plane.table.load_full();
+        let route = table.routes.get(peer.as_bytes())?;
+        let via = EndpointId::from_bytes(&route.next.first()?.peer).ok()?;
+        Some(RouteSummary {
+            hops: route.hops,
+            via,
         })
     }
 
-    /// Stable logical link, preserved across topology changes.
+    /// The kinds of transport with an open direct link to a peer, best
+    /// first.
+    pub fn direct_kinds(&self, peer: EndpointId) -> Vec<String> {
+        let state = self.state();
+        state
+            .ordered(peer.as_bytes())
+            .into_iter()
+            .filter(|raw| !raw.link.is_closed())
+            .map(|raw| raw.kind.clone())
+            .collect()
+    }
+
+    /// Stable end-to-end channel for a protocol, preserved across topology
+    /// and transport changes.
     pub fn link(&self, peer: EndpointId, protocol: &str) -> Arc<PeerLink> {
-        let mut protocols = self.protocols();
+        let mut state = self.state();
-        let state = self.protocol(&mut protocols, protocol);
+        let key = (*peer.as_bytes(), protocol.to_owned());
-        if let Some(link) = state.links.get(peer.as_bytes()) {
+        if let Some(link) = state.links.get(&key) {
             return link.clone();
         }
         let (inbox_tx, inbox_rx) = mpsc::channel(INBOX);
@@ -321,88 +419,118 @@ impl RelayHub {
         let link = Arc::new(PeerLink {
             network: self.network,
             peer,
+            tag: envelope::protocol_tag(protocol),
             plane: state.plane.clone(),
             inbox_tx,
             inbox_rx: tokio::sync::Mutex::new(inbox_rx),
             closed,
         });
-        state.links.insert(*peer.as_bytes(), link.clone());
+        state.links.insert(key, link.clone());
         state.publish();
         link
     }
 
-    /// Whether the protocol already owns its logical link.
+    /// Whether the protocol already owns its end-to-end channel to a peer.
     pub fn has_link(&self, peer: EndpointId, protocol: &str) -> bool {
-        self.protocols()
+        self.state()
-            .get(protocol)
+            .links
-            .is_some_and(|state| state.links.contains_key(peer.as_bytes()))
+            .contains_key(&(*peer.as_bytes(), protocol.to_owned()))
     }
 
     /// Installs a raw transport link and starts its independent ingress reader.
-    pub fn set_direct(&self, peer: EndpointId, protocol: &str, raw: SharedLink) {
+    ///
+    /// A neighbour may have one link per kind of transport; installing a
+    /// second of the same kind replaces the first.
+    pub fn set_direct(&self, peer: EndpointId, kind: &str, raw: SharedLink) {
         if raw.network() != self.network || raw.peer() != peer {
             return;
         }
-        let mut protocols = self.protocols();
+        let mut state = self.state();
-        let state = self.protocol(&mut protocols, protocol);
         let id = *peer.as_bytes();
-        if let Some(old) = state.readers.remove(&id) {
-            old.abort();
-        }
-        state.raw.insert(id, raw.clone());
-        state.publish();
         let plane = state.plane.clone();
         let changed = self.changed.clone();
-        state.readers.insert(
+        let reader_link = raw.clone();
-            id,
+        let reader = tokio::spawn(async move {
-            tokio::spawn(async move {
+            let mut batch = 0;
-                let mut batch = 0;
+            while let Some(frame) = reader_link.recv().await {
-                while let Some(frame) = raw.recv().await {
+                plane.receive(id, frame);
-                    plane.receive(id, frame);
+                batch += 1;
-                    batch += 1;
+                if batch == 64 {
-                    if batch == 64 {
+                    tokio::task::yield_now().await;
-                        tokio::task::yield_now().await;
+                    batch = 0;
-                        batch = 0;
-                    }
                 }
-                changed.notify_one();
+            }
-            }),
+            changed.notify_one();
-        );
+        });
+        let links = state.raw.entry(id).or_default();
+        if let Some(position) = links.iter().position(|known| known.kind == kind) {
+            links.remove(position).reader.abort();
+        }
+        links.push(RawLink {
+            kind: kind.to_owned(),
+            link: raw,
+            reader,
+        });
+        state.publish();
     }
 
-    /// Removes a physical link without tearing down end-to-end protocol state.
+    /// Removes one physical link without tearing down end-to-end protocol state.
-    pub fn clear_direct(&self, peer: EndpointId, protocol: &str) {
+    pub fn clear_direct(&self, peer: EndpointId, kind: &str) {
-        if let Some(state) = self.protocols().get_mut(protocol) {
+        let mut state = self.state();
-            state.raw.remove(peer.as_bytes());
+        let mut changed = false;
-            if let Some(task) = state.readers.remove(peer.as_bytes()) {
+        if let Some(links) = state.raw.get_mut(peer.as_bytes()) {
-                task.abort();
+            if let Some(position) = links.iter().position(|known| known.kind == kind) {
+                links.remove(position).reader.abort();
+                changed = true;
             }
+            if links.is_empty() {
+                state.raw.remove(peer.as_bytes());
+            }
+        }
+        if changed {
             state.publish();
         }
     }
 
     /// Revokes all links and topology involving a departed authenticated peer.
     pub fn remove_peer(&self, peer: EndpointId) {
-        for state in self.protocols().values_mut() {
+        let mut state = self.state();
-            state.raw.remove(peer.as_bytes());
+        if let Some(links) = state.raw.remove(peer.as_bytes()) {
-            if let Some(task) = state.readers.remove(peer.as_bytes()) {
+            for raw in links {
-                task.abort();
+                raw.reader.abort();
             }
-            if let Some(link) = state.links.remove(peer.as_bytes()) {
+        }
+        let gone: Vec<_> = state
+            .links
+            .keys()
+            .filter(|(id, _)| id == peer.as_bytes())
+            .cloned()
+            .collect();
+        for key in gone {
+            if let Some(link) = state.links.remove(&key) {
                 link.close();
             }
-            state.members.remove(peer.as_bytes());
-            state.graph.remove(peer.as_bytes());
-            for neighbors in state.graph.values_mut() {
-                neighbors.retain(|id| id != peer.as_bytes());
-            }
-            state.publish();
         }
+        state.members.remove(peer.as_bytes());
+        state.graph.remove(peer.as_bytes());
+        for neighbors in state.graph.values_mut() {
+            neighbors.retain(|id| id != peer.as_bytes());
+        }
+        state.publish();
     }
 
     /// Stops every reader and releases all transport handles.
     pub fn close(&self) {
-        self.protocols().clear();
+        let mut state = self.state();
+        state.stop_readers();
+        state.raw.clear();
+        for link in state.links.values() {
+            link.close();
+        }
+        state.links.clear();
+        state.graph.clear();
+        state.members.clear();
+        state.plane.table.store(Arc::default());
     }
 }
 
@@ -411,6 +539,7 @@ impl RelayHub {
 pub struct PeerLink {
     network: NetworkId,
     peer: EndpointId,
+    tag: u64,
     plane: Arc<Plane>,
     inbox_tx: mpsc::Sender<Bytes>,
     inbox_rx: tokio::sync::Mutex<mpsc::Receiver<Bytes>>,
@@ -454,10 +583,11 @@ impl PacketLink for PeerLink {
         let hop = route
             .select(&self.plane.local, flow)
             .ok_or(TransportError::Closed)?;
-        hop.link.send(envelope::encode(
+        hop.send(envelope::encode(
             self.plane.local,
             *self.peer.as_bytes(),
             flow,
+            self.tag,
             &payload,
         ))?;
         if route.hops > 1 {
@@ -489,7 +619,9 @@ impl PacketLink for PeerLink {
     fn path_description(&self) -> String {
         let table = self.plane.table.load();
         match table.routes.get(self.peer.as_bytes()) {
-            Some(route) if route.hops == 1 => route.next[0].link.path_description(),
+            Some(route) if route.hops == 1 => route.next[0]
+                .first_open()
+                .map_or_else(|| "unreachable".into(), |link| link.path_description()),
             Some(route) => format!(
                 "relay {} hops via {} ({} equal paths)",
                 route.hops,

crates/tsunagi-core/src/dataplane/relay_tests.rs

@@ -16,6 +16,9 @@ fn peer(seed: u8) -> EndpointId {
 fn id(seed: u8) -> PeerId {
     *peer(seed).as_bytes()
 }
+fn tag() -> u64 {
+    envelope::protocol_tag("ip")
+}
 
 #[derive(Debug)]
 struct Wire {
@@ -78,9 +81,8 @@ impl PacketLink for Wire {
     }
 }
 
-fn topology(hub: &RelayHub, protocol: &str, edges: &[(u8, &[u8])], members: &[u8]) {
+fn topology(hub: &RelayHub, edges: &[(u8, &[u8])], members: &[u8]) {
     hub.set_topology(
-        protocol,
         edges
             .iter()
             .map(|(a, bs)| (id(*a), bs.iter().map(|b| id(*b)).collect()))
@@ -96,7 +98,7 @@ async fn ecmp_is_per_flow_direct_wins_and_existing_tunnel_survives_changes() {
     let c = Wire::new(3, true);
     hub.set_direct(peer(2), "ip", b.clone());
     hub.set_direct(peer(3), "ip", c.clone());
-    topology(&hub, "ip", &[(2, &[4]), (3, &[4])], &[1, 2, 3, 4]);
+    topology(&hub, &[(2, &[4]), (3, &[4])], &[1, 2, 3, 4]);
     let link = hub.link(peer(4), "ip");
     let mut chosen = HashMap::new();
     for _ in 0..8 {
@@ -132,7 +134,7 @@ async fn ecmp_is_per_flow_direct_wins_and_existing_tunnel_survives_changes() {
     }
     assert_eq!(c.take().len(), 100);
     hub.clear_direct(peer(2), "ip");
-    topology(&hub, "ip", &[(3, &[])], &[1, 2, 3, 4]);
+    topology(&hub, &[(3, &[])], &[1, 2, 3, 4]);
     assert!(link.send(Bytes::new()).is_err());
     assert!(!link.is_closed());
     assert!(Arc::ptr_eq(&link, &hub.link(peer(4), "ip")));
@@ -152,8 +154,8 @@ async fn transport_reader_forwards_without_any_plugin_reader_and_isolates_protoc
     let c = Wire::new(3, true);
     hub.set_direct(peer(1), "ip", a.clone());
     hub.set_direct(peer(3), "ip", c.clone());
-    topology(&hub, "ip", &[(3, &[4])], &[1, 2, 3, 4]);
+    topology(&hub, &[(3, &[4])], &[1, 2, 3, 4]);
-    let frame = envelope::encode(id(1), id(4), 91, b"end-to-end encrypted");
+    let frame = envelope::encode(id(1), id(4), 91, tag(), b"end-to-end encrypted");
     let pointer = frame.as_ptr();
     a.feed.send(frame).await.unwrap();
     tokio::time::timeout(std::time::Duration::from_secs(1), async {
@@ -170,12 +172,136 @@ async fn transport_reader_forwards_without_any_plugin_reader_and_isolates_protoc
         ROUTING_HOP_LIMIT - 1
     );
     assert_eq!(&sent[0][RELAY_OVERHEAD..], b"end-to-end encrypted");
-    let isolated = hub.link(peer(4), "other-ip");
-    assert!(isolated.send(Bytes::new()).is_err());
     assert_eq!(hub.counters().forwarded, 1);
     hub.close();
 }
 
+#[tokio::test]
+async fn a_frame_is_delivered_only_to_the_protocol_it_names() {
+    let hub = RelayHub::new(network(), peer(2));
+    hub.set_direct(peer(1), "ip", Wire::new(1, true));
+    let ip = hub.link(peer(1), "ip");
+    let other = hub.link(peer(1), "other-ip");
+    let plane = ip.plane.clone();
+    plane.receive(id(1), envelope::encode(id(1), id(2), 0, tag(), b"for ip"));
+    plane.receive(
+        id(1),
+        envelope::encode(
+            id(1),
+            id(2),
+            0,
+            envelope::protocol_tag("other-ip"),
+            b"for other",
+        ),
+    );
+    plane.receive(
+        id(1),
+        envelope::encode(
+            id(1),
+            id(2),
+            0,
+            envelope::protocol_tag("nobody-runs-this"),
+            b"for nobody",
+        ),
+    );
+    assert_eq!(ip.recv().await.unwrap(), Bytes::from_static(b"for ip"));
+    assert_eq!(
+        other.recv().await.unwrap(),
+        Bytes::from_static(b"for other")
+    );
+    assert_eq!(hub.counters().dropped_unknown, 1);
+    hub.close();
+}
+
+/// A middle member joins two neighbours over different transports, and the
+/// two ends share a protocol the middle has never heard of.
+#[tokio::test]
+async fn a_tunnel_crosses_a_middle_member_whose_links_are_of_different_kinds() {
+    let a = RelayHub::new(network(), peer(1));
+    let c = RelayHub::new(network(), peer(3));
+    let b = RelayHub::new(network(), peer(2));
+    let a_to_c = Wire::new(3, true);
+    let c_to_a = Wire::new(1, true);
+    let c_to_b = Wire::new(2, true);
+    let b_to_c = Wire::new(3, true);
+    a.set_direct(peer(3), "wg", a_to_c.clone());
+    c.set_direct(peer(1), "wg", c_to_a);
+    c.set_direct(peer(2), "wg-quic", c_to_b.clone());
+    b.set_direct(peer(3), "wg-quic", b_to_c.clone());
+    topology(&a, &[(3, &[1, 2])], &[1, 2, 3]);
+    topology(&b, &[(3, &[1, 2])], &[1, 2, 3]);
+    topology(&c, &[(1, &[3]), (2, &[3])], &[1, 2, 3]);
+
+    let outgoing = a.link(peer(2), "tunnel");
+    let incoming = b.link(peer(1), "tunnel");
+    outgoing
+        .send_flow(Bytes::from_static(b"sealed"), 5)
+        .unwrap();
+    let frame = a_to_c.take().remove(0);
+
+    // The middle forwards it onto its other kind of link without looking
+    // inside.
+    c.state().plane.receive(id(1), frame);
+    let frame = c_to_b.take().remove(0);
+    assert_eq!(c.counters().forwarded, 1);
+
+    b.state().plane.receive(id(3), frame);
+    assert_eq!(
+        incoming.recv().await.unwrap(),
+        Bytes::from_static(b"sealed")
+    );
+    assert_eq!(b.counters().received_via, 1);
+    assert_eq!(
+        b.route(peer(1)),
+        Some(RouteSummary {
+            hops: 2,
+            via: peer(3)
+        })
+    );
+    a.close();
+    b.close();
+    c.close();
+}
+
+#[tokio::test]
+async fn a_neighbour_is_reached_over_the_preferred_kind_and_falls_back_when_it_is_lost() {
+    let hub = RelayHub::new(network(), peer(1));
+    hub.set_priority(vec!["wg".into(), "tcp-tls".into(), "wg-quic".into()]);
+    let slow = Wire::new(2, true);
+    let fast = Wire::new(2, true);
+    hub.set_direct(peer(2), "wg-quic", slow.clone());
+    let link = hub.link(peer(2), "tunnel");
+    link.send(Bytes::from_static(b"one")).unwrap();
+    assert_eq!(slow.take().len(), 1);
+    assert_eq!(hub.direct_kinds(peer(2)), ["wg-quic"]);
+
+    // A better kind appears: traffic moves to it with nothing to redo.
+    hub.set_direct(peer(2), "wg", fast.clone());
+    assert_eq!(hub.direct_kinds(peer(2)), ["wg", "wg-quic"]);
+    link.send(Bytes::from_static(b"two")).unwrap();
+    assert_eq!(fast.take().len(), 1);
+    assert!(slow.take().is_empty());
+
+    // It dies: the worse one carries on, and the logical link is untouched.
+    fast.dead.store(true, Ordering::Relaxed);
+    link.send(Bytes::from_static(b"three")).unwrap();
+    assert_eq!(slow.take().len(), 1);
+    assert!(!link.is_closed());
+    assert_eq!(
+        hub.route(peer(2)),
+        Some(RouteSummary {
+            hops: 1,
+            via: peer(2)
+        })
+    );
+
+    hub.clear_direct(peer(2), "wg-quic");
+    hub.clear_direct(peer(2), "wg");
+    assert!(!hub.reachable(peer(2)));
+    assert!(Arc::ptr_eq(&link, &hub.link(peer(2), "tunnel")));
+    hub.close();
+}
+
 #[tokio::test]
 async fn local_delivery_is_bounded_and_malformed_or_unknown_sources_are_dropped() {
     let hub = RelayHub::new(network(), peer(2));
@@ -184,18 +310,21 @@ async fn local_delivery_is_bounded_and_malformed_or_unknown_sources_are_dropped(
     let link = hub.link(peer(1), "ip");
     let plane = link.plane.clone();
     for _ in 0..INBOX + 1 {
-        plane.receive(id(1), envelope::encode(id(1), id(2), 0, b"ip"));
+        plane.receive(id(1), envelope::encode(id(1), id(2), 0, tag(), b"ip"));
     }
     assert_eq!(hub.counters().dropped_congested, 1);
     for _ in 0..INBOX {
         assert_eq!(link.recv().await.unwrap(), Bytes::from_static(b"ip"));
     }
     plane.receive(id(1), Bytes::from_static(b"broken"));
-    plane.receive(id(1), envelope::encode(id(9), id(2), 0, b"unknown member"));
+    plane.receive(
+        id(1),
+        envelope::encode(id(9), id(2), 0, tag(), b"unknown member"),
+    );
     assert_eq!(hub.counters().dropped_unknown, 2);
     plane.receive(
         id(1),
-        envelope::encode(id(1), id(9), 0, b"unknown destination"),
+        envelope::encode(id(1), id(9), 0, tag(), b"unknown destination"),
     );
     assert_eq!(hub.counters().dropped_no_link, 1);
     hub.close();
@@ -210,11 +339,11 @@ async fn inconsistent_tables_cannot_loop_beyond_the_hop_limit() {
     a.set_direct(peer(2), "ip", ab.clone());
     b.set_direct(peer(1), "ip", ba.clone());
     // Deliberately inconsistent snapshots while updates are in flight.
-    topology(&a, "ip", &[(2, &[4])], &[1, 2, 3, 4]);
+    topology(&a, &[(2, &[4])], &[1, 2, 3, 4]);
-    topology(&b, "ip", &[(1, &[4])], &[1, 2, 3, 4]);
+    topology(&b, &[(1, &[4])], &[1, 2, 3, 4]);
     let ap = a.link(peer(4), "ip").plane.clone();
     let bp = b.link(peer(4), "ip").plane.clone();
-    let mut frame = envelope::encode(id(3), id(4), 7, b"transit");
+    let mut frame = envelope::encode(id(3), id(4), 7, tag(), b"transit");
     for turn in 0..ROUTING_HOP_LIMIT {
         let (plane, incoming, wire) = if turn % 2 == 0 {
             (&ap, id(2), &ab)
@@ -253,7 +382,7 @@ async fn forwarding_benchmark() {
     hub.set_direct(peer(3), "ip", wire.clone());
     let alternate = Wire::new(5, false);
     hub.set_direct(peer(5), "ip", alternate.clone());
-    topology(&hub, "ip", &[(3, &[4]), (5, &[4])], &[1, 2, 3, 4, 5]);
+    topology(&hub, &[(3, &[4]), (5, &[4])], &[1, 2, 3, 4, 5]);
     let plane = hub.link(peer(4), "ip").plane.clone();
     let source = id(1);
     let destination = id(4);
@@ -264,7 +393,9 @@ async fn forwarding_benchmark() {
         const BATCHES: usize = 100;
         for _ in 0..BATCHES {
             let frames: Vec<_> = (0..COUNT)
-                .map(|flow| envelope::encode(source, destination, flow as u64, &vec![42; size]))
+                .map(|flow| {
+                    envelope::encode(source, destination, flow as u64, tag(), &vec![42; size])
+                })
                 .collect();
             let start = std::time::Instant::now();
             for frame in frames {

crates/tsunagi-core/src/dataplane/routing/envelope.rs

@@ -3,8 +3,8 @@ use super::{FlowId, PeerId};
 use crate::config::{MAX_DATA_DATAGRAM, ROUTING_HOP_LIMIT};
 use bytes::{BufMut, Bytes, BytesMut};
 
-pub(crate) const HEADER: usize = 2 + 32 + 32 + 8;
+pub(crate) const HEADER: usize = 2 + 32 + 32 + 8 + 8;
-const VERSION: u8 = 1;
+const VERSION: u8 = 2;
 
 #[derive(Debug, PartialEq, Eq)]
 pub(crate) struct Header {
@@ -12,6 +12,15 @@ pub(crate) struct Header {
     pub destination: PeerId,
     pub remaining: u8,
     pub flow: FlowId,
+    /// Which end-to-end protocol the payload belongs to, whatever links carry it.
+    pub protocol: u64,
+}
+
+/// A stable 64-bit tag for a protocol id (FNV-1a), the same on every member.
+pub(crate) fn protocol_tag(name: &str) -> u64 {
+    name.bytes().fold(0xcbf2_9ce4_8422_2325, |hash, byte| {
+        (hash ^ u64::from(byte)).wrapping_mul(0x0000_0100_0000_01b3)
+    })
 }
 
 pub(crate) fn decode(bytes: &[u8]) -> Option<Header> {
@@ -28,16 +37,24 @@ pub(crate) fn decode(bytes: &[u8]) -> Option<Header> {
         destination: bytes[34..66].try_into().ok()?,
         remaining: bytes[1],
         flow: u64::from_be_bytes(bytes[66..74].try_into().ok()?),
+        protocol: u64::from_be_bytes(bytes[74..82].try_into().ok()?),
     })
 }
 
-pub(crate) fn encode(source: PeerId, destination: PeerId, flow: FlowId, payload: &[u8]) -> Bytes {
+pub(crate) fn encode(
+    source: PeerId,
+    destination: PeerId,
+    flow: FlowId,
+    protocol: u64,
+    payload: &[u8],
+) -> Bytes {
     let mut bytes = BytesMut::with_capacity(HEADER + payload.len());
     bytes.put_u8(VERSION);
     bytes.put_u8(ROUTING_HOP_LIMIT);
     bytes.extend_from_slice(&source);
     bytes.extend_from_slice(&destination);
     bytes.put_u64(flow);
+    bytes.put_u64(protocol);
     bytes.extend_from_slice(payload);
     bytes.freeze()
 }
@@ -58,7 +75,7 @@ mod tests {
     use super::*;
     #[test]
     fn transit_reuses_the_buffer_and_rejects_invalid_headers() {
-        let frame = encode([1; 32], [2; 32], 17, &[42; 1280]);
+        let frame = encode([1; 32], [2; 32], 17, protocol_tag("wg"), &[42; 1280]);
         let address = frame.as_ptr();
         let frame = decrement(frame);
         assert_eq!(
@@ -66,7 +83,10 @@ mod tests {
             address,
             "no payload copy for an owned buffer"
         );
-        assert_eq!(decode(&frame).unwrap().remaining, ROUTING_HOP_LIMIT - 1);
+        let header = decode(&frame).unwrap();
+        assert_eq!(header.remaining, ROUTING_HOP_LIMIT - 1);
+        assert_eq!(header.protocol, protocol_tag("wg"));
+        assert_ne!(protocol_tag("wg"), protocol_tag("wg-quic"));
         assert_eq!(&frame[HEADER..], &[42; 1280]);
         for length in 0..HEADER {
             assert!(decode(&frame[..length]).is_none());

crates/tsunagi-core/src/error.rs

@@ -120,6 +120,13 @@ pub enum Error {
         what: String,
     },
 
+    /// The request is understood and cannot be done as things stand.
+    #[error("{reason}")]
+    Rejected {
+        /// Why, phrased so the message stands on its own.
+        reason: String,
+    },
+
     /// Discovery backend failure. Never fatal for the agent.
     #[error("discovery error: {0}")]
     Discovery(String),

crates/tsunagi-core/src/ipc/mod.rs

@@ -214,7 +214,7 @@ pub enum Request {
     ///
     /// Asked of the running agent because that is the only way to add a
     /// network to an agent that is already up: the state directory belongs
-    /// to one live agent, so a second `tsunagi up` cannot.
+    /// to one live agent, so a second `tsng up` cannot.
     Join {
         /// The network name.
         name: String,
@@ -234,6 +234,22 @@ pub enum Request {
         /// Which network, by the id text `status` prints.
         network_id: String,
     },
+    /// Offer this agent as an exit node in one network, or stop. Off unless
+    /// asked.
+    SetExitOffer {
+        /// Public network identifier.
+        network_id: String,
+        /// Whether members may send their internet traffic through this agent.
+        enabled: bool,
+    },
+    /// Send all this device's internet traffic through a member of one
+    /// network, or back the ordinary way.
+    SetExitNode {
+        /// Public network identifier.
+        network_id: String,
+        /// The member's endpoint id, or `None` to stop using an exit node.
+        peer: Option<String>,
+    },
 }
 
 impl std::fmt::Debug for Request {
@@ -255,6 +271,13 @@ impl std::fmt::Debug for Request {
             }
             Request::Join { name, .. } => write!(f, "Join {{ name: {name}, secret: <redacted> }}"),
             Request::Secret { network_id } => write!(f, "Secret {{ {network_id} }}"),
+            Request::SetExitOffer {
+                network_id,
+                enabled,
+            } => write!(f, "SetExitOffer {{ {network_id}, enabled: {enabled} }}"),
+            Request::SetExitNode { network_id, peer } => {
+                write!(f, "SetExitNode {{ {network_id}, peer: {peer:?} }}")
+            }
         }
     }
 }
@@ -281,6 +304,10 @@ pub enum Response {
     Dns(Option<DnsReport>),
     /// A network's shared secret, redacted in `Debug`.
     Secret(RedactedText),
+    /// Whether this agent now offers itself as an exit node.
+    ExitOffer(bool),
+    /// The member this device now sends its internet traffic through.
+    ExitNode(Option<String>),
     /// The request could not be served.
     Error(String),
 }
@@ -352,6 +379,38 @@ pub struct StatusReport {
     pub networks: Vec<NetworkReport>,
     /// The local DNS service, when one was asked for.
     pub dns: Option<DnsReport>,
+    /// The state directory the agent is actually using.
+    ///
+    /// A client that was not told one would look in its own default, which is
+    /// not the agent's when the agent runs as a service under another user.
+    pub state_dir: String,
+    /// The cache directory the agent is actually using.
+    pub cache_dir: String,
+    /// The executable the agent runs, which is what needs the capability.
+    pub program: String,
+    /// Whether the agent itself can manage the overlay interface.
+    ///
+    /// It is the agent that creates the interface, so the client's own
+    /// capabilities say nothing about it.
+    pub privilege: PrivilegeReport,
+    /// The version of the agent's software.
+    pub version: String,
+    /// The data plane protocols it has, each as `name vN` (wire version).
+    pub protocols: Vec<String>,
+}
+
+/// What the agent found when it checked whether it may manage an interface.
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub enum PrivilegeReport {
+    /// Not checked.
+    #[default]
+    Unknown,
+    /// It can.
+    Available,
+    /// It cannot, with what was found.
+    Missing(String),
+    /// This platform has no provisioner yet.
+    Unsupported,
 }
 
 /// The local DNS service.
@@ -425,6 +484,41 @@ pub struct NetworkReport {
     pub range_conflict: Option<String>,
     /// The overlay, when a protocol is running one.
     pub overlay: Option<OverlayReport>,
+    /// This agent's own name, when another member claimed it first.
+    pub hostname_conflict: Option<HostnameConflictReport>,
+    /// Exit-node settings: whether this agent offers one, and whether it
+    /// uses one.
+    pub exit: ExitReport,
+}
+
+/// How packets reach a member right now.
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub enum DataPathReport {
+    /// Nothing carries packets to it: it is away, or only connected for
+    /// control while a data path is being set up.
+    #[default]
+    None,
+    /// A direct link.
+    Direct {
+        /// The kind of transport carrying it, e.g. `wg`.
+        transport: String,
+    },
+    /// Through other members.
+    Relayed {
+        /// Number of links on the way, at least two.
+        hops: u8,
+        /// The member the first of them goes to, as an endpoint id.
+        via: String,
+    },
+}
+
+/// A name somebody else claimed first.
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct HostnameConflictReport {
+    /// The name that is taken.
+    pub name: String,
+    /// The member that holds it, as an endpoint id.
+    pub holder: String,
 }
 
 /// One member of the network, from signed state.
@@ -436,6 +530,17 @@ pub struct MemberReport {
     pub overlay_address_v4: Option<String>,
     /// Consecutive failed dial attempts, when this agent is trying to reach it.
     pub failed_dials: u32,
+    /// The last hostname this agent saw it announce, kept while it is away.
+    pub hostname: Option<String>,
+    /// Whether this agent can reach it now, by any path. The one answer
+    /// every client gives to "is it online": a member reached through
+    /// others is online, over a longer path.
+    pub online: bool,
+    /// How packets reach it.
+    pub path: DataPathReport,
+    /// The name it claimed, when somebody else claimed it first. It still
+    /// works by address; it is not found by that name.
+    pub hostname_conflict: Option<HostnameConflictReport>,
 }
 
 /// One control plane peer.
@@ -450,6 +555,10 @@ pub struct PeerReport {
     pub transport: String,
     /// Round-trip time in milliseconds, when a path is selected.
     pub rtt_ms: Option<u64>,
+    /// The peer offers itself as an exit node in this network.
+    pub exit_node: bool,
+    /// How packets reach it.
+    pub path: DataPathReport,
 }
 
 /// The WireGuard overlay of one network.
@@ -482,6 +591,35 @@ pub struct OverlayReport {
     pub broadcast_rules: Option<HostRulesReport>,
 }
 
+/// How one set of exit-node host rules went.
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct RuleSetReport {
+    /// Whether every step took.
+    pub ok: bool,
+    /// One line: what is in place, or what is missing and why.
+    pub detail: String,
+}
+
+/// One network's exit-node settings and what they are doing.
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ExitReport {
+    /// This agent offers itself as an exit node in this network.
+    pub offering: bool,
+    /// Masquerading and forwarding rules for members' traffic, when offering.
+    pub offer_rules: Option<RuleSetReport>,
+    /// Whether the kernel forwards packets for the overlay interface.
+    /// `Some(false)` means the rules are in place and nothing passes until it
+    /// is turned on. `None` when unknown.
+    pub forwarding: Option<bool>,
+    /// The member this device sends its internet traffic through, as an
+    /// endpoint id.
+    pub via: Option<String>,
+    /// Whether that member is connected and still offering to be one.
+    pub via_online: bool,
+    /// The routes that send this device's traffic through it.
+    pub client_rules: Option<RuleSetReport>,
+}
+
 /// What the agent installed on the host so LAN broadcast reaches the overlay.
 #[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
 pub struct HostRulesReport {
@@ -632,6 +770,28 @@ pub trait ReportSource: Send + Sync + 'static {
     ) -> BoxFuture<'_, std::result::Result<String, String>> {
         Box::pin(async move { Err("this agent cannot read secrets".to_string()) })
     }
+
+    /// Offers this agent as an exit node in a network, or stops.
+    ///
+    /// Defaulted to a refusal, like the others.
+    fn set_exit_offer(
+        &self,
+        _network_id: String,
+        _enabled: bool,
+    ) -> BoxFuture<'_, std::result::Result<bool, String>> {
+        Box::pin(async move { Err("this agent cannot be an exit node".to_string()) })
+    }
+
+    /// Sends this device's internet traffic through a member, or stops.
+    ///
+    /// Defaulted to a refusal, like the others.
+    fn set_exit_node(
+        &self,
+        _network_id: String,
+        _peer: Option<String>,
+    ) -> BoxFuture<'_, std::result::Result<Option<String>, String>> {
+        Box::pin(async move { Err("this agent cannot use an exit node".to_string()) })
+    }
 }
 
 impl<F> ReportSource for F
@@ -647,7 +807,7 @@ where
 ///
 /// A local answer comes from memory, so anything this slow means the agent is
 /// wedged rather than busy. Saying so beats waiting: unbounded, one wedged
-/// runtime leaves `tsunagi status` hanging with nothing on screen and no way
+/// runtime leaves `tsng status` hanging with nothing on screen and no way
 /// out but Ctrl-C.
 pub const EXCHANGE_TIMEOUT: Duration = Duration::from_secs(5);
 
@@ -662,7 +822,7 @@ pub const EXCHANGE_TIMEOUT: Duration = Duration::from_secs(5);
 ///
 /// Bump it whenever [`Request`], [`Response`] or anything they contain
 /// changes shape.
-pub const CONTROL_PROTOCOL: u32 = u32::from_be_bytes([b'T', b'S', b'N', 17]);
+pub const CONTROL_PROTOCOL: u32 = u32::from_be_bytes([b'T', b'S', b'N', 18]);
 
 /// Reads one request off an accepted stream, answers it, writes the response.
 ///
@@ -724,6 +884,19 @@ where
             Ok(secret) => Response::Secret(RedactedText::new(secret)),
             Err(reason) => Response::Error(reason),
         },
+        Request::SetExitOffer {
+            network_id,
+            enabled,
+        } => match source.set_exit_offer(network_id, enabled).await {
+            Ok(enabled) => Response::ExitOffer(enabled),
+            Err(reason) => Response::Error(reason),
+        },
+        Request::SetExitNode { network_id, peer } => {
+            match source.set_exit_node(network_id, peer).await {
+                Ok(peer) => Response::ExitNode(peer),
+                Err(reason) => Response::Error(reason),
+            }
+        }
     };
     write_message(&mut stream, &response).await
 }
@@ -878,6 +1051,41 @@ pub async fn set_dns(
     }
 }
 
+/// Offers the running agent as an exit node in one network, or stops.
+pub async fn set_exit_offer(
+    path: impl AsRef<Path>,
+    network_id: &str,
+    enabled: bool,
+) -> Result<bool> {
+    let request = Request::SetExitOffer {
+        network_id: network_id.to_owned(),
+        enabled,
+    };
+    match exchange(path.as_ref(), &request, EXCHANGE_TIMEOUT).await? {
+        Response::ExitOffer(enabled) => Ok(enabled),
+        Response::Error(message) => Err(Error::Storage(message)),
+        other => Err(Error::Storage(format!("unexpected answer: {other:?}"))),
+    }
+}
+
+/// Sends the running agent's internet traffic through a member of one
+/// network, or back the ordinary way with `None`.
+pub async fn set_exit_node(
+    path: impl AsRef<Path>,
+    network_id: &str,
+    peer: Option<&str>,
+) -> Result<Option<String>> {
+    let request = Request::SetExitNode {
+        network_id: network_id.to_owned(),
+        peer: peer.map(str::to_owned),
+    };
+    match exchange(path.as_ref(), &request, EXCHANGE_TIMEOUT).await? {
+        Response::ExitNode(peer) => Ok(peer),
+        Response::Error(message) => Err(Error::Storage(message)),
+        other => Err(Error::Storage(format!("unexpected answer: {other:?}"))),
+    }
+}
+
 /// Asks a running agent for a configured network's shared secret, in its
 /// `tsn1…` text form, so a local client can copy it. The secret is never
 /// logged by this path.

crates/tsunagi-core/src/ipc/windows.rs

@@ -210,7 +210,7 @@ impl Drop for ControlSocket {
 /// Accepts one client at a time, keeping a fresh instance ready for the next.
 ///
 /// A named pipe server instance serves a single client, so a new instance is
-/// created as soon as one is taken — otherwise a second `tsunagi status` while
+/// created as soon as one is taken — otherwise a second `tsng status` while
 /// the first is mid-flight would find nothing listening.
 async fn serve(
     name: String,
@@ -294,7 +294,7 @@ pub(crate) async fn connect(path: &Path) -> Result<NamedPipeClient> {
                         format!(
                             "the agent's control pipe exists, but Windows denied access. \
                              Run this command as the same Windows user and with the same \
-                             elevation as `tsunagi up` (use an administrator terminal if \
+                             elevation as `tsng up` (use an administrator terminal if \
                              the agent is elevated). Windows error: {err}"
                         ),
                     ),

crates/tsunagi-core/src/overlay/broadcast.rs

@@ -140,6 +140,7 @@ mod tests {
     fn limited_and_directed_broadcasts_never_cross_domains_or_target_disabled_peers() {
         let peer = iroh::SecretKey::from_bytes(&[8; 32]).public();
         let a = NetworkRoutes {
+            exit: Default::default(),
             range: Some("10.0.0.0/24".parse().unwrap()),
             local: Some("10.0.0.1".parse().unwrap()),
             peers: vec![("10.0.0.2".parse().unwrap(), peer)],
@@ -149,6 +150,7 @@ mod tests {
             },
         };
         let b = NetworkRoutes {
+            exit: Default::default(),
             range: Some("10.1.0.0/24".parse().unwrap()),
             local: Some("10.1.0.1".parse().unwrap()),
             peers: vec![("10.1.0.2".parse().unwrap(), peer)],
@@ -185,6 +187,7 @@ mod tests {
         assert!(!table.accepts(id("b"), peer, Ipv4Addr::BROADCAST));
         assert!(table.accepts(id("a"), peer, Ipv4Addr::BROADCAST));
         let disabled = NetworkRoutes {
+            exit: Default::default(),
             broadcast: BroadcastPolicy {
                 enabled: false,
                 ..a.broadcast.clone()

crates/tsunagi-core/src/overlay/exit.rs

@@ -0,0 +1,32 @@
+//! Exit-node host rules: what makes this device an exit node for others, and
+//! what sends this device's own traffic through one.
+//!
+//! The packet side lives in [`super::router`]; this is the side the operating
+//! system sees. It is kept apart from the broadcast rules, which have a
+//! different lifetime and different tags.
+
+/// How one set of host rules went.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct RuleSetReport {
+    /// Whether every step took.
+    pub ok: bool,
+    /// One line: what is in place, or what is missing and why.
+    pub detail: String,
+}
+
+/// What the host rules of one network's exit-node settings are doing.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct ExitRulesReport {
+    /// Masquerading and forwarding for members' traffic, when this agent
+    /// offers itself as an exit node here. `None` means none are wanted.
+    pub offer: Option<RuleSetReport>,
+    /// Whether the kernel forwards packets for the overlay interface.
+    ///
+    /// `Some(false)` means the rules are in place but nothing passes until
+    /// forwarding is turned on, which the agent never does itself. `None`
+    /// when it could not be read.
+    pub forwarding: Option<bool>,
+    /// The routes that send this device's traffic through its exit node.
+    /// `None` means it uses none through this network.
+    pub client: Option<RuleSetReport>,
+}

crates/tsunagi-core/src/overlay/hostrules/exit.rs

@@ -0,0 +1,263 @@
+//! Host rules for exit nodes: what the operating system needs for this agent
+//! to carry other members' internet traffic, and for this device's own
+//! traffic to go through a member.
+//!
+//! Two independent halves, planned together because one interface carries
+//! both:
+//!
+//! * **Offering** — one set of rules per network that offers this agent as an
+//!   exit node, chosen by that network's range: masquerade the range out of
+//!   every other interface and let it through the forward chain. A network
+//!   that does not offer has no rules, so its members' packets are dropped by
+//!   the firewall as well as by the agent.
+//! * **Using** — policy routing that sends everything the host does not have
+//!   a more specific route for into the overlay interface, while the agent's
+//!   own sockets keep the ordinary route (see `linux_exit`).
+//!
+//! Nothing a peer announces becomes a host setting. Offering is the owner's
+//! switch; using is the user's choice of a member. Every object is tagged,
+//! reversible, and removed when it is no longer wanted, when the network
+//! leaves or stops, and when the agent stops.
+
+use std::sync::{Arc, Mutex};
+
+use crate::BoxFuture;
+use crate::state::Ipv4Range;
+
+use super::RuleOutcome;
+
+/// What the host should hold for one interface's exit settings.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct ExitHostPlan {
+    /// The overlay interface.
+    pub interface: String,
+    /// The ranges of every network that offers this agent as an exit node.
+    pub offer: Vec<Ipv4Range>,
+    /// Whether this device sends its internet traffic through a member.
+    pub client: bool,
+    /// The range of every network on the interface. Only the using side
+    /// reads it, to keep this agent's own traffic *to* the overlay inside it
+    /// where the host has no per-user routing (macOS).
+    pub overlay: Vec<Ipv4Range>,
+    /// Underlay addresses this agent talks to directly and must keep reaching
+    /// outside the overlay's default route. Only filled while `client` is set
+    /// and only for hosts that report [`ExitHostRules::needs_bypass`].
+    pub bypass: Vec<std::net::Ipv4Addr>,
+    /// Host names (relay servers) that must stay reachable the same way; the
+    /// host rules resolve them.
+    pub bypass_hosts: Vec<String>,
+}
+
+impl ExitHostPlan {
+    /// Whether there is nothing to hold.
+    pub fn is_empty(&self) -> bool {
+        self.offer.is_empty() && !self.client
+    }
+}
+
+/// What applying a plan achieved.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct ExitHostReport {
+    /// One outcome per offered range: its masquerade and forward rules.
+    pub offer: Vec<(Ipv4Range, RuleOutcome)>,
+    /// Whether the kernel forwards packets for the interface. `None` when it
+    /// could not be read. The agent only reads this: turning forwarding on is
+    /// the owner's decision.
+    pub forwarding: Option<bool>,
+    /// The routes and rules that send this device's traffic through the
+    /// interface, when the plan asked for them.
+    pub client: Option<RuleOutcome>,
+}
+
+/// Installs and removes exit-node rules for an overlay interface.
+///
+/// Like the broadcast rules, no call fails as a whole: a step that cannot be
+/// done is in the report, because the caller's only useful response is to
+/// say so.
+pub trait ExitHostRules: Send + Sync + std::fmt::Debug + 'static {
+    /// Makes the host match the plan, replacing what this agent put there
+    /// for the interface before.
+    fn apply<'a>(&'a self, plan: &'a ExitHostPlan) -> BoxFuture<'a, ExitHostReport>;
+
+    /// Removes everything this agent put there for the interface. Succeeds
+    /// when nothing is there: it runs on the shutdown path, and once at
+    /// startup to take away what a crashed run left.
+    fn clear<'a>(&'a self, interface: &'a str) -> BoxFuture<'a, ()>;
+
+    /// Whether using an exit node on this host needs the underlay addresses
+    /// the agent talks to, because the host cannot exempt the agent's own
+    /// traffic from the default route by user id (Windows). The default is no.
+    fn needs_bypass(&self) -> bool {
+        false
+    }
+}
+
+/// The tag every firewall object of one offered range carries.
+pub fn exit_tag(interface: &str, range: &Ipv4Range) -> String {
+    format!("{}{range}", exit_tag_prefix(interface))
+}
+
+/// The start of every tag for an interface; what cleanup selects by.
+pub fn exit_tag_prefix(interface: &str) -> String {
+    format!("tsunagi-exit:{interface}:")
+}
+
+/// The one-line detail for a set of offer outcomes.
+pub fn offer_detail(outcome: &RuleOutcome, range: &Ipv4Range) -> String {
+    match outcome {
+        RuleOutcome::Applied => format!("masquerade + forward for {range} in place"),
+        RuleOutcome::Failed(reason) => reason.clone(),
+    }
+}
+
+/// An in-memory host for exit rules, for tests: nothing is touched.
+#[derive(Debug, Clone, Default)]
+pub struct MockExitRules {
+    state: Arc<Mutex<Option<ExitHostPlan>>>,
+    calls: Arc<Mutex<Vec<String>>>,
+    forwarding: Arc<Mutex<Option<bool>>>,
+    failure: Arc<Mutex<Option<String>>>,
+    needs_bypass: Arc<Mutex<bool>>,
+}
+
+impl MockExitRules {
+    /// An empty host with forwarding turned on.
+    pub fn new() -> Self {
+        let rules = Self::default();
+        *lock(&rules.forwarding) = Some(true);
+        rules
+    }
+
+    /// What the host reports for kernel forwarding from now on.
+    pub fn set_forwarding(&self, forwarding: Option<bool>) {
+        *lock(&self.forwarding) = forwarding;
+    }
+
+    /// Whether this host asks for the underlay addresses, like Windows.
+    pub fn set_needs_bypass(&self, needs: bool) {
+        *lock(&self.needs_bypass) = needs;
+    }
+
+    /// Makes every step fail with this reason from now on.
+    pub fn fail_with(&self, reason: Option<String>) {
+        *lock(&self.failure) = reason;
+    }
+
+    /// What is installed now.
+    pub fn installed(&self) -> Option<ExitHostPlan> {
+        lock(&self.state).clone()
+    }
+
+    /// Every `apply:<interface>` / `clear:<interface>` call, in order.
+    pub fn calls(&self) -> Vec<String> {
+        lock(&self.calls).clone()
+    }
+}
+
+fn lock<T>(mutex: &Mutex<T>) -> std::sync::MutexGuard<'_, T> {
+    match mutex.lock() {
+        Ok(guard) => guard,
+        Err(poisoned) => poisoned.into_inner(),
+    }
+}
+
+impl ExitHostRules for MockExitRules {
+    fn needs_bypass(&self) -> bool {
+        *lock(&self.needs_bypass)
+    }
+
+    fn apply<'a>(&'a self, plan: &'a ExitHostPlan) -> BoxFuture<'a, ExitHostReport> {
+        Box::pin(async move {
+            lock(&self.calls).push(format!("apply:{}", plan.interface));
+            let outcome = match lock(&self.failure).clone() {
+                Some(reason) => RuleOutcome::Failed(reason),
+                None => {
+                    *lock(&self.state) = Some(plan.clone());
+                    RuleOutcome::Applied
+                }
+            };
+            ExitHostReport {
+                offer: plan
+                    .offer
+                    .iter()
+                    .map(|range| (*range, outcome.clone()))
+                    .collect(),
+                forwarding: *lock(&self.forwarding),
+                client: plan.client.then_some(outcome),
+            }
+        })
+    }
+
+    fn clear<'a>(&'a self, interface: &'a str) -> BoxFuture<'a, ()> {
+        Box::pin(async move {
+            lock(&self.calls).push(format!("clear:{interface}"));
+            *lock(&self.state) = None;
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
+
+    use super::*;
+
+    fn range() -> Ipv4Range {
+        "10.13.37.0/24".parse().unwrap()
+    }
+
+    #[test]
+    fn tags_name_the_interface_and_the_range() {
+        assert_eq!(
+            exit_tag("tsun0", &range()),
+            "tsunagi-exit:tsun0:10.13.37.0/24"
+        );
+        assert!(exit_tag("tsun0", &range()).starts_with(&exit_tag_prefix("tsun0")));
+        // Another interface's tag never matches this one's prefix.
+        assert!(!exit_tag("tsun01", &range()).starts_with(&exit_tag_prefix("tsun0")));
+    }
+
+    #[test]
+    fn an_empty_plan_is_nothing_to_hold() {
+        let mut plan = ExitHostPlan::default();
+        assert!(plan.is_empty());
+        plan.client = true;
+        assert!(!plan.is_empty());
+    }
+
+    #[tokio::test]
+    async fn the_mock_applies_reports_and_clears() {
+        let rules = MockExitRules::new();
+        let plan = ExitHostPlan {
+            interface: "tsun0".into(),
+            offer: vec![range()],
+            client: true,
+            overlay: vec![range()],
+            ..Default::default()
+        };
+        let report = rules.apply(&plan).await;
+        assert_eq!(report.offer[0].1, RuleOutcome::Applied);
+        assert_eq!(report.forwarding, Some(true));
+        assert_eq!(report.client, Some(RuleOutcome::Applied));
+        assert_eq!(rules.installed(), Some(plan));
+
+        rules.set_forwarding(Some(false));
+        rules.fail_with(Some("denied".into()));
+        let report = rules
+            .apply(&ExitHostPlan {
+                interface: "tsun0".into(),
+                offer: vec![range()],
+                client: false,
+                overlay: Vec::new(),
+                ..Default::default()
+            })
+            .await;
+        assert_eq!(report.forwarding, Some(false));
+        assert!(matches!(report.offer[0].1, RuleOutcome::Failed(_)));
+        assert_eq!(report.client, None);
+
+        rules.clear("tsun0").await;
+        assert_eq!(rules.installed(), None);
+        assert_eq!(rules.calls(), ["apply:tsun0", "apply:tsun0", "clear:tsun0"]);
+    }
+}

crates/tsunagi-core/src/overlay/hostrules/linux.rs

@@ -50,7 +50,7 @@ fn pick_iptables(exists: impl Fn(&str) -> bool) -> Option<&'static str> {
 
 /// What running `iptables` produced.
 #[derive(Debug, Clone, PartialEq, Eq)]
-enum Ran {
+pub(super) enum Ran {
     /// There is no `iptables` to run.
     Missing,
     /// It ran, and exited like this.
@@ -63,32 +63,76 @@ enum Ran {
 
 /// Runs `iptables` with these arguments. A function value so the flow below
 /// can be tested without touching the host.
-type Run<'a> = &'a dyn Fn(&[String]) -> Ran;
+pub(super) type Run<'a> = &'a dyn Fn(&[String]) -> Ran;
 
 /// The match and target of the rule, without the chain or position.
-fn rule_spec(plan: &BroadcastRulesPlan) -> Vec<String> {
+///
-    [
+/// `comment` false leaves the tag off, for a kernel that has no `comment`
-        "-i",
+/// match; the rule is then recognised by its shape, see [`tagged_deletions`].
-        plan.interface.as_str(),
+fn rule_spec(plan: &BroadcastRulesPlan, comment: bool) -> Vec<String> {
-        "-p",
+    let range = plan.range.to_string();
-        "udp",
+    let tag = plan.tag();
-        "-s",
+    let mut words = vec!["-i", plan.interface.as_str(), "-p", "udp", "-s", &range];
-        &plan.range.to_string(),
+    if comment {
-        "-m",
+        words.extend(["-m", "comment", "--comment", &tag]);
-        "comment",
+    }
-        "--comment",
+    words.extend(["-j", "ACCEPT"]);
-        &plan.tag(),
+    words.into_iter().map(str::to_string).collect()
-        "-j",
+}
-        "ACCEPT",
+
-    ]
+/// Whether the kernel has the `comment` match, which a rule needs to carry
-    .into_iter()
+/// its tag. Asked of iptables itself: checking a rule that does not exist
-    .map(str::to_string)
+/// fails either way, but only a missing match says so.
-    .collect()
+pub(super) fn comment_supported(run: Run<'_>) -> bool {
+    let probe = locked(
+        [
+            "-t",
+            "filter",
+            "-C",
+            "FORWARD",
+            "-m",
+            "comment",
+            "--comment",
+            "tsunagi-probe",
+            "-j",
+            "ACCEPT",
+        ]
+        .map(str::to_string),
+    );
+    match run(&probe) {
+        Ran::Exited {
+            success: false,
+            stderr,
+            ..
+        } => !stderr.contains("No chain/target/match by that name"),
+        _ => true,
+    }
+}
+
+/// `iptables -S` words as option clauses: an option with its value, a negated
+/// one with its `!`. It prints the options in its own order, not the one a
+/// rule was written in, so rules are compared by their clauses, sorted.
+fn clauses(words: &[String]) -> Vec<String> {
+    let mut out = Vec::new();
+    let mut at = 0;
+    while at < words.len() {
+        let take = if words[at] == "!" { 3 } else { 2 };
+        let end = (at + take).min(words.len());
+        out.push(words[at..end].join(" "));
+        at = end;
+    }
+    out.sort();
+    out
+}
+
+/// Whether two rules say the same thing, whatever order they list it in.
+pub(super) fn same_rule(a: &[String], b: &[String]) -> bool {
+    clauses(a) == clauses(b)
 }
 
 /// Waits briefly for the xtables lock instead of failing when another tool
 /// holds it.
-fn locked(args: impl IntoIterator<Item = String>) -> Vec<String> {
+pub(super) fn locked(args: impl IntoIterator<Item = String>) -> Vec<String> {
     ["-w", "5"]
         .into_iter()
         .map(str::to_string)
@@ -96,19 +140,19 @@ fn locked(args: impl IntoIterator<Item = String>) -> Vec<String> {
         .collect()
 }
 
-fn check_args(plan: &BroadcastRulesPlan) -> Vec<String> {
+fn check_args(plan: &BroadcastRulesPlan, comment: bool) -> Vec<String> {
     locked(
         ["-C".to_string(), CHAIN.to_string()]
             .into_iter()
-            .chain(rule_spec(plan)),
+            .chain(rule_spec(plan, comment)),
     )
 }
 
-fn insert_args(plan: &BroadcastRulesPlan) -> Vec<String> {
+fn insert_args(plan: &BroadcastRulesPlan, comment: bool) -> Vec<String> {
     locked(
         ["-I".to_string(), CHAIN.to_string(), "1".to_string()]
             .into_iter()
-            .chain(rule_spec(plan)),
+            .chain(rule_spec(plan, comment)),
     )
 }
 
@@ -118,7 +162,7 @@ fn list_args() -> Vec<String> {
 
 /// Splits one `iptables -S` line into words, honouring double quotes, which
 /// `iptables` puts around comments that need them.
-fn split_rule_line(line: &str) -> Vec<String> {
+pub(super) fn split_rule_line(line: &str) -> Vec<String> {
     let mut words = Vec::new();
     let mut current = String::new();
     let mut quoted = false;
@@ -147,8 +191,28 @@ fn split_rule_line(line: &str) -> Vec<String> {
     words
 }
 
+/// Whether a rule is the one this module writes for some range of the
+/// interface the tag belongs to, with no comment on it.
+fn is_uncommented_rule(tag: &str, rest: &[String]) -> bool {
+    let Some(interface) = tag.strip_prefix("tsunagi:") else {
+        return false;
+    };
+    let Some(range) = rest
+        .windows(2)
+        .find(|pair| pair[0] == "-s")
+        .map(|pair| pair[1].as_str())
+    else {
+        return false;
+    };
+    let ours: Vec<String> = ["-i", interface, "-p", "udp", "-s", range, "-j", "ACCEPT"]
+        .map(str::to_string)
+        .to_vec();
+    same_rule(&ours, rest)
+}
+
 /// The delete commands for every rule in an `iptables -S INPUT` listing that
-/// carries exactly this tag. Anything else in the chain is left alone.
+/// carries exactly this tag, or, with no `comment` match in the kernel, is
+/// exactly the rule written for some range. Anything else is left alone.
 fn tagged_deletions(listing: &str, tag: &str) -> Vec<Vec<String>> {
     listing
         .lines()
@@ -162,7 +226,8 @@ fn tagged_deletions(listing: &str, tag: &str) -> Vec<Vec<String>> {
             }
             let tagged = rest
                 .windows(2)
-                .any(|pair| pair[0] == "--comment" && pair[1] == tag);
+                .any(|pair| pair[0] == "--comment" && pair[1] == tag)
+                || is_uncommented_rule(tag, rest);
             tagged.then(|| {
                 locked(
                     ["-D".to_string(), CHAIN.to_string()]
@@ -175,7 +240,7 @@ fn tagged_deletions(listing: &str, tag: &str) -> Vec<Vec<String>> {
 }
 
 /// A failure message with the likely fix for the likely cause.
-fn failure(stderr: &str) -> String {
+pub(super) fn failure(stderr: &str) -> String {
     let text = stderr.trim();
     let lower = text.to_ascii_lowercase();
     if lower.contains("permission denied") || lower.contains("must be root") {
@@ -197,7 +262,8 @@ fn missing(plan: &BroadcastRulesPlan) -> String {
 
 /// Makes the firewall hold exactly one rule for this interface, the planned one.
 fn apply_firewall(run: Run<'_>, plan: &BroadcastRulesPlan) -> RuleOutcome {
-    let present = match run(&check_args(plan)) {
+    let comment = comment_supported(run);
+    let present = match run(&check_args(plan, comment)) {
         Ran::Missing => return RuleOutcome::Failed(missing(plan)),
         Ran::Exited { success, .. } => success,
     };
@@ -227,7 +293,7 @@ fn apply_firewall(run: Run<'_>, plan: &BroadcastRulesPlan) -> RuleOutcome {
             return RuleOutcome::Failed(failure(&stderr));
         }
     }
-    match run(&insert_args(plan)) {
+    match run(&insert_args(plan, comment)) {
         Ran::Missing => RuleOutcome::Failed(missing(plan)),
         Ran::Exited { success: true, .. } => RuleOutcome::Applied,
         Ran::Exited { stderr, .. } => RuleOutcome::Failed(failure(&stderr)),
@@ -261,7 +327,7 @@ fn clear_firewall(run: Run<'_>, interface: &str) {
 }
 
 /// Runs the real `iptables`.
-fn run_iptables(args: &[String]) -> Ran {
+pub(super) fn run_iptables(args: &[String]) -> Ran {
     let Some(program) = pick_iptables(|path| std::path::Path::new(path).is_file()) else {
         return Ran::Missing;
     };
@@ -283,7 +349,7 @@ fn run_iptables(args: &[String]) -> Ran {
 /// The Linux implementation: netlink for the route, `iptables` for the rule.
 #[derive(Debug)]
 pub struct LinuxHostRules {
-    route: RouteHandle,
+    pub(super) route: RouteHandle,
 }
 
 impl LinuxHostRules {
@@ -306,6 +372,10 @@ impl BroadcastHostRules for LinuxHostRules {
         "netlink+iptables"
     }
 
+    fn exit_rules(&self) -> Option<&dyn super::ExitHostRules> {
+        Some(self)
+    }
+
     fn apply<'a>(&'a self, plan: &'a BroadcastRulesPlan) -> BoxFuture<'a, BroadcastRulesReport> {
         Box::pin(async move {
             let route = self.set_route(plan.interface.clone(), plan.source).await;
@@ -361,7 +431,7 @@ mod tests {
 
     #[test]
     fn the_rule_is_udp_only_from_the_overlay_range_on_this_interface() {
-        let spec = words(&rule_spec(&plan()));
+        let spec = words(&rule_spec(&plan(), true));
         assert_eq!(
             spec,
             "-i tsun0 -p udp -s 10.13.37.0/24 -m comment --comment tsunagi:tsun0 -j ACCEPT"
@@ -369,8 +439,8 @@ mod tests {
         // Nothing here may widen to other protocols or every source.
         assert!(spec.contains("-p udp"));
         assert!(!spec.contains("0.0.0.0/0"));
-        assert!(words(&insert_args(&plan())).starts_with("-w 5 -I INPUT 1 -i tsun0"));
+        assert!(words(&insert_args(&plan(), true)).starts_with("-w 5 -I INPUT 1 -i tsun0"));
-        assert!(words(&check_args(&plan())).starts_with("-w 5 -C INPUT -i tsun0"));
+        assert!(words(&check_args(&plan(), true)).starts_with("-w 5 -C INPUT -i tsun0"));
     }
 
     #[test]
@@ -404,6 +474,49 @@ mod tests {
         assert!(tagged_deletions("", "tsunagi:tsun0").is_empty());
     }
 
+    #[test]
+    fn a_kernel_without_the_comment_match_says_so_in_its_error() {
+        let answer = |stderr: &'static str| {
+            move |_: &[String]| Ran::Exited {
+                success: false,
+                stdout: String::new(),
+                stderr: stderr.to_string(),
+            }
+        };
+        assert!(!comment_supported(&answer(
+            "iptables: No chain/target/match by that name."
+        )));
+        assert!(comment_supported(&answer(
+            "iptables: Bad rule (does a matching rule exist in that chain?)."
+        )));
+        assert!(comment_supported(&|_: &[String]| Ran::Missing));
+    }
+
+    #[test]
+    fn a_rule_written_without_a_comment_is_found_by_its_shape() {
+        // Listed the way iptables prints it: its own option order.
+        let listing = "\
+-P INPUT ACCEPT
+-A INPUT -s 10.13.37.0/24 -i tsun0 -p udp -j ACCEPT
+-A INPUT -s 10.99.0.0/16 -i tsun0 -p udp -j ACCEPT
+-A INPUT -s 10.13.37.0/24 -i tsun1 -p udp -j ACCEPT
+-A INPUT -s 10.13.37.0/24 -i tsun0 -p udp -j DROP
+-A INPUT -s 10.13.37.0/24 -i tsun0 -p tcp -j ACCEPT
+";
+        let deletions = tagged_deletions(listing, "tsunagi:tsun0");
+        assert_eq!(deletions.len(), 2, "{deletions:?}");
+        assert!(words(&deletions[0]).ends_with("-s 10.13.37.0/24 -i tsun0 -p udp -j ACCEPT"));
+        assert!(words(&deletions[1]).contains("10.99.0.0/16"));
+    }
+
+    #[test]
+    fn without_a_comment_the_rule_has_none() {
+        let with = words(&rule_spec(&plan(), true));
+        let without = words(&rule_spec(&plan(), false));
+        assert!(with.contains("-m comment --comment tsunagi:tsun0"));
+        assert_eq!(without, "-i tsun0 -p udp -s 10.13.37.0/24 -j ACCEPT");
+    }
+
     /// A scripted `iptables`: answers by the leading verb, records every call.
     struct Fake {
         calls: RefCell<Vec<String>>,
@@ -424,6 +537,14 @@ mod tests {
             }
         }
         fn run(&self, args: &[String]) -> Ran {
+            // The probe for the `comment` match: not part of what is tested.
+            if args.iter().any(|word| word == "tsunagi-probe") {
+                return Ran::Exited {
+                    success: false,
+                    stdout: String::new(),
+                    stderr: "Bad rule".into(),
+                };
+            }
             self.calls.borrow_mut().push(words(args));
             if self.missing {
                 return Ran::Missing;

crates/tsunagi-core/src/overlay/hostrules/linux_exit.rs

@@ -0,0 +1,813 @@
+//! Exit-node host rules on Linux: `iptables` for the offering side, policy
+//! routing over netlink for the using side.
+//!
+//! # Offering
+//!
+//! For every network that offers this agent as an exit node, three rules,
+//! selected by that network's range and carrying the tag
+//! `tsunagi-exit:<if>:<range>`:
+//!
+//! ```text
+//! -t nat    POSTROUTING  -s <range> ! -o <if> -j MASQUERADE
+//! -t filter FORWARD      -i <if> -s <range> ! -o <if> -j ACCEPT
+//! -t filter FORWARD      -o <if> -d <range> -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT
+//! ```
+//!
+//! `! -o <if>` is the egress without naming it: whatever interface the
+//! default route uses, now or after it changes. Kernel forwarding is only
+//! *read*. Turning it on changes how the whole host behaves, which is the
+//! owner's decision, so when it is off the rules are installed anyway and the
+//! report says so.
+//!
+//! # Using
+//!
+//! Policy routing, with no `/1` routes and nothing in the main table:
+//!
+//! ```text
+//! table 0x7473:  default dev <if>
+//! 5280: from all uidrange <euid>-<euid> lookup main
+//! 5290: from all lookup main suppress_prefixlength 0
+//! 5300: from all lookup 0x7473
+//! ```
+//!
+//! The first keeps the agent's *own* sockets off the tunnel: its QUIC, relay,
+//! DHT and DNS traffic would otherwise be routed into the interface it is
+//! carrying, a loop. The second lets every specific route — the LAN, another
+//! VPN, a tunnel to somewhere else — keep working, because only the default
+//! route is suppressed. The priorities sit after Tailscale's 5270.
+//!
+//! The first rule exempts a *user id*, so it is only right when the agent has
+//! one of its own, as the packaged service does. An agent started from a login
+//! session would take that user's own applications out of the tunnel with it,
+//! and the exit node would silently do nothing for them. That is refused, not
+//! guessed at: see [`client_refusal`].
+
+use crate::BoxFuture;
+use crate::state::Ipv4Range;
+
+use super::RuleOutcome;
+use super::exit::{ExitHostPlan, ExitHostReport, ExitHostRules, exit_tag, exit_tag_prefix};
+use super::linux::{
+    LinuxHostRules, Ran, Run, comment_supported, failure, locked, run_iptables, same_rule,
+    split_rule_line,
+};
+
+/// The chains the offering rules live in: `(table, chain)`.
+const CHAINS: [(&str, &str); 2] = [("nat", "POSTROUTING"), ("filter", "FORWARD")];
+
+/// One firewall rule: where it goes, and its match and target.
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct Rule {
+    table: &'static str,
+    chain: &'static str,
+    spec: Vec<String>,
+}
+
+fn owned(words: &[&str]) -> Vec<String> {
+    words.iter().map(|word| word.to_string()).collect()
+}
+
+/// The three rules of one offered range.
+///
+/// Each carries a comment naming its interface and range, which is how it is
+/// found again. A kernel without the `comment` match (small router builds
+/// leave it out) cannot take that, so `comment` false leaves it off and the
+/// rules are recognised by their shape instead; see [`tagged_rules`].
+fn offer_rules(interface: &str, range: &Ipv4Range, comment: bool) -> Vec<Rule> {
+    let range_text = range.to_string();
+    let tag = exit_tag(interface, range);
+    let comment: Vec<String> = if comment {
+        owned(&["-m", "comment", "--comment", tag.as_str()])
+    } else {
+        Vec::new()
+    };
+    let spec = |head: &[&str], tail: &[&str]| -> Vec<String> {
+        owned(head)
+            .into_iter()
+            .chain(comment.iter().cloned())
+            .chain(owned(tail))
+            .collect()
+    };
+    vec![
+        Rule {
+            table: "nat",
+            chain: "POSTROUTING",
+            spec: spec(
+                &["-s", &range_text, "!", "-o", interface],
+                &["-j", "MASQUERADE"],
+            ),
+        },
+        Rule {
+            table: "filter",
+            chain: "FORWARD",
+            spec: spec(
+                &["-i", interface, "-s", &range_text, "!", "-o", interface],
+                &["-j", "ACCEPT"],
+            ),
+        },
+        Rule {
+            table: "filter",
+            chain: "FORWARD",
+            spec: spec(
+                &[
+                    "-o",
+                    interface,
+                    "-d",
+                    &range_text,
+                    "-m",
+                    "conntrack",
+                    "--ctstate",
+                    "RELATED,ESTABLISHED",
+                ],
+                &["-j", "ACCEPT"],
+            ),
+        },
+    ]
+}
+
+fn check_args(rule: &Rule) -> Vec<String> {
+    locked(
+        owned(&["-t", rule.table, "-C", rule.chain])
+            .into_iter()
+            .chain(rule.spec.iter().cloned()),
+    )
+}
+
+fn insert_args(rule: &Rule) -> Vec<String> {
+    locked(
+        owned(&["-t", rule.table, "-I", rule.chain, "1"])
+            .into_iter()
+            .chain(rule.spec.iter().cloned()),
+    )
+}
+
+fn list_args(table: &str, chain: &str) -> Vec<String> {
+    locked(owned(&["-t", table, "-S", chain]))
+}
+
+/// A rule found in a listing whose comment starts with our prefix.
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct Found {
+    /// The whole tag.
+    tag: String,
+    /// The words after `-A <chain>`, which is what `-D` needs.
+    rest: Vec<String>,
+}
+
+/// Every rule in an `iptables -S <chain>` listing that is ours: carrying a
+/// tag that starts with `prefix`, or, on a kernel with no `comment` match,
+/// being exactly one of the three rules this module writes for some range.
+/// Anything else in the chain is left alone.
+fn tagged_rules(listing: &str, chain: &str, prefix: &str) -> Vec<Found> {
+    // `tsunagi-exit:<interface>:`
+    let interface = prefix
+        .strip_prefix("tsunagi-exit:")
+        .and_then(|rest| rest.strip_suffix(':'))
+        .unwrap_or_default();
+    listing
+        .lines()
+        .filter_map(|line| {
+            let words = split_rule_line(line);
+            let [append, found_chain, rest @ ..] = words.as_slice() else {
+                return None;
+            };
+            if append != "-A" || found_chain != chain {
+                return None;
+            }
+            let tag = rest
+                .windows(2)
+                .find(|pair| pair[0] == "--comment" && pair[1].starts_with(prefix))
+                .map(|pair| pair[1].clone())
+                .or_else(|| uncommented_tag(interface, chain, rest))?;
+            Some(Found {
+                tag,
+                rest: rest.to_vec(),
+            })
+        })
+        .collect()
+}
+
+/// The tag a rule would have carried, when it is one of ours written without
+/// a comment: its words are those of the rule for the range it names.
+fn uncommented_tag(interface: &str, chain: &str, rest: &[String]) -> Option<String> {
+    if interface.is_empty() {
+        return None;
+    }
+    let range: Ipv4Range = rest
+        .windows(2)
+        .find(|pair| pair[0] == "-s" || pair[0] == "-d")
+        .and_then(|pair| pair[1].parse().ok())?;
+    offer_rules(interface, &range, false)
+        .iter()
+        .any(|rule| rule.chain == chain && same_rule(&rule.spec, rest))
+        .then(|| exit_tag(interface, &range))
+}
+
+fn delete_args(table: &str, chain: &str, found: &Found) -> Vec<String> {
+    locked(
+        owned(&["-t", table, "-D", chain])
+            .into_iter()
+            .chain(found.rest.iter().cloned()),
+    )
+}
+
+fn missing_iptables(range: &Ipv4Range, interface: &str) -> String {
+    format!(
+        "iptables not found; install it (the iptables-nft package is enough), or masquerade \
+         {range} out of every interface but `{interface}` and forward it yourself"
+    )
+}
+
+/// Reads one chain, or says why not.
+fn read_chain(run: Run<'_>, table: &str, chain: &str) -> Result<String, Failure> {
+    match run(&list_args(table, chain)) {
+        Ran::Missing => Err(Failure::Missing),
+        Ran::Exited {
+            success: true,
+            stdout,
+            ..
+        } => Ok(stdout),
+        Ran::Exited { stderr, .. } => Err(Failure::Failed(failure(&stderr))),
+    }
+}
+
+enum Failure {
+    Missing,
+    Failed(String),
+}
+
+/// Deletes found rules; the first failure ends it.
+fn delete_all(
+    run: Run<'_>,
+    table: &str,
+    chain: &str,
+    found: &[Found],
+    keep: impl Fn(&Found) -> bool,
+) -> Result<(), String> {
+    for rule in found.iter().filter(|rule| !keep(rule)) {
+        if let Ran::Exited {
+            success: false,
+            stderr,
+            ..
+        } = run(&delete_args(table, chain, rule))
+        {
+            return Err(failure(&stderr));
+        }
+    }
+    Ok(())
+}
+
+/// Makes the firewall hold exactly the offering rules of these ranges for the
+/// interface, and no others of ours.
+fn apply_offer(
+    run: Run<'_>,
+    interface: &str,
+    ranges: &[Ipv4Range],
+) -> Vec<(Ipv4Range, RuleOutcome)> {
+    let fail_all = |reason: String| -> Vec<(Ipv4Range, RuleOutcome)> {
+        ranges
+            .iter()
+            .map(|range| (*range, RuleOutcome::Failed(reason.clone())))
+            .collect()
+    };
+    let prefix = exit_tag_prefix(interface);
+    let wanted: Vec<String> = ranges.iter().map(|r| exit_tag(interface, r)).collect();
+    let comment = comment_supported(run);
+
+    // What is there now, per chain.
+    let mut present: Vec<(&str, &str, Vec<Found>)> = Vec::new();
+    for (table, chain) in CHAINS {
+        match read_chain(run, table, chain) {
+            Ok(listing) => present.push((table, chain, tagged_rules(&listing, chain, &prefix))),
+            Err(Failure::Missing) => {
+                return match ranges.first() {
+                    Some(range) => fail_all(missing_iptables(range, interface)),
+                    None => Vec::new(),
+                };
+            }
+            Err(Failure::Failed(reason)) => return fail_all(reason),
+        }
+    }
+
+    // Rules for a range no longer offered, or left by an earlier run.
+    for (table, chain, found) in &present {
+        if let Err(reason) = delete_all(run, table, chain, found, |rule| wanted.contains(&rule.tag))
+        {
+            return fail_all(reason);
+        }
+    }
+
+    ranges
+        .iter()
+        .map(|range| {
+            let rules = offer_rules(interface, range, comment);
+            let tag = exit_tag(interface, range);
+            let in_place = rules
+                .iter()
+                .all(|rule| matches!(run(&check_args(rule)), Ran::Exited { success: true, .. }))
+                && present.iter().all(|(_, chain, found)| {
+                    let have = found.iter().filter(|rule| rule.tag == tag).count();
+                    have == rules.iter().filter(|rule| rule.chain == *chain).count()
+                });
+            if in_place {
+                return (*range, RuleOutcome::Applied);
+            }
+            // Start this range from a clean slate: a half-installed set, or
+            // one that differs from the plan, is replaced as a whole.
+            for (table, chain, found) in &present {
+                if let Err(reason) = delete_all(run, table, chain, found, |rule| rule.tag != tag) {
+                    return (*range, RuleOutcome::Failed(reason));
+                }
+            }
+            for rule in &rules {
+                match run(&insert_args(rule)) {
+                    Ran::Missing => {
+                        return (
+                            *range,
+                            RuleOutcome::Failed(missing_iptables(range, interface)),
+                        );
+                    }
+                    Ran::Exited { success: true, .. } => {}
+                    Ran::Exited { stderr, .. } => {
+                        return (*range, RuleOutcome::Failed(failure(&stderr)));
+                    }
+                }
+            }
+            (*range, RuleOutcome::Applied)
+        })
+        .collect()
+}
+
+/// Removes every offering rule of ours for the interface. Best effort.
+fn clear_offer(run: Run<'_>, interface: &str) {
+    let prefix = exit_tag_prefix(interface);
+    for (table, chain) in CHAINS {
+        let Ok(listing) = read_chain(run, table, chain) else {
+            continue;
+        };
+        let found = tagged_rules(&listing, chain, &prefix);
+        if let Err(reason) = delete_all(run, table, chain, &found, |_| false) {
+            tracing::warn!(
+                interface,
+                "cannot remove an exit node firewall rule: {reason}"
+            );
+        }
+    }
+}
+
+/// The kernel's forwarding switch for packets arriving on the interface,
+/// read from the text of the sysctl files. Never written.
+fn forwarding_state(read: impl Fn(&str) -> Option<String>, interface: &str) -> Option<bool> {
+    let flag = |text: String| match text.trim() {
+        "1" => Some(true),
+        "0" => Some(false),
+        _ => None,
+    };
+    // The name is derived here, but it ends up in a path.
+    if !interface.is_empty() && !interface.contains(['/', '\0']) && interface != ".." {
+        let per_interface = format!("/proc/sys/net/ipv4/conf/{interface}/forwarding");
+        if let Some(state) = read(&per_interface).and_then(flag) {
+            return Some(state);
+        }
+    }
+    read("/proc/sys/net/ipv4/ip_forward").and_then(flag)
+}
+
+fn read_sysctl(path: &str) -> Option<String> {
+    std::fs::read_to_string(path).ok()
+}
+
+/// The effective user id from the text of `/proc/self/status`.
+fn parse_euid(status: &str) -> Option<u32> {
+    status
+        .lines()
+        .find_map(|line| line.strip_prefix("Uid:"))
+        .and_then(|rest| rest.split_whitespace().nth(1))
+        .and_then(|effective| effective.parse().ok())
+}
+
+/// Why the using side must not be installed for this process, if it must not.
+///
+/// The bypass rule exempts this process's *user id* from the tunnel. That is
+/// right for a service with an id of its own and wrong for a process started
+/// from somebody's login session, which shares its id with every application
+/// that person runs. A login session is recognised by `XDG_RUNTIME_DIR`,
+/// which `systemd --user` and the login managers set and a system service
+/// does not. Crude on purpose: refusing a service that was started oddly is
+/// a message, and exempting a user's applications is a silent failure.
+fn client_refusal(xdg_runtime_dir: Option<&str>) -> Option<String> {
+    xdg_runtime_dir.filter(|dir| !dir.is_empty()).map(|_| {
+        "the exit node needs the agent to run as a system service with a user of its own: \
+         this agent was started from a login session, so routing everything through the \
+         overlay would take that user's own applications out of the tunnel with it"
+            .to_string()
+    })
+}
+
+impl LinuxHostRules {
+    async fn blocking<T: Send + 'static>(
+        work: impl FnOnce() -> T + Send + 'static,
+    ) -> Result<T, String> {
+        tokio::task::spawn_blocking(work)
+            .await
+            .map_err(|err| format!("the task failed: {err}"))
+    }
+
+    async fn apply_client(&self, interface: &str) -> RuleOutcome {
+        let xdg = std::env::var("XDG_RUNTIME_DIR").ok();
+        if let Some(reason) = client_refusal(xdg.as_deref()) {
+            // Whatever an earlier run left must not stay in force.
+            self.clear_client().await;
+            return RuleOutcome::Failed(reason);
+        }
+        let Some(euid) = std::fs::read_to_string("/proc/self/status")
+            .ok()
+            .and_then(|status| parse_euid(&status))
+        else {
+            return RuleOutcome::Failed("cannot tell which user this agent runs as".to_string());
+        };
+        let route = self.route.clone();
+        let interface = interface.to_string();
+        match Self::blocking(move || route.set_exit_client(&interface, euid)).await {
+            Ok(Ok(())) => RuleOutcome::Applied,
+            Ok(Err(err)) => RuleOutcome::Failed(err.to_string()),
+            Err(reason) => RuleOutcome::Failed(reason),
+        }
+    }
+
+    async fn clear_client(&self) {
+        let route = self.route.clone();
+        if let Ok(Err(err)) = Self::blocking(move || route.clear_exit_client()).await {
+            tracing::warn!(%err, "cannot remove the exit node routing rules");
+        }
+    }
+}
+
+impl ExitHostRules for LinuxHostRules {
+    fn apply<'a>(&'a self, plan: &'a ExitHostPlan) -> BoxFuture<'a, ExitHostReport> {
+        Box::pin(async move {
+            let interface = plan.interface.clone();
+            let ranges = plan.offer.clone();
+            let offer = {
+                let (job_interface, job_ranges) = (interface.clone(), ranges.clone());
+                Self::blocking(move || apply_offer(&run_iptables, &job_interface, &job_ranges))
+                    .await
+                    .unwrap_or_else(|reason| {
+                        ranges
+                            .iter()
+                            .map(|range| (*range, RuleOutcome::Failed(reason.clone())))
+                            .collect()
+                    })
+            };
+            let forwarding = if ranges.is_empty() {
+                None
+            } else {
+                forwarding_state(read_sysctl, &interface)
+            };
+            let client = if plan.client {
+                Some(self.apply_client(&interface).await)
+            } else {
+                self.clear_client().await;
+                None
+            };
+            ExitHostReport {
+                offer,
+                forwarding,
+                client,
+            }
+        })
+    }
+
+    fn clear<'a>(&'a self, interface: &'a str) -> BoxFuture<'a, ()> {
+        Box::pin(async move {
+            let name = interface.to_string();
+            let _ = Self::blocking(move || clear_offer(&run_iptables, &name)).await;
+            self.clear_client().await;
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
+
+    use std::cell::RefCell;
+
+    use super::*;
+
+    fn range() -> Ipv4Range {
+        "10.13.37.0/24".parse().unwrap()
+    }
+
+    fn words(args: &[String]) -> String {
+        args.join(" ")
+    }
+
+    #[test]
+    fn the_rules_masquerade_the_range_out_of_every_other_interface_and_forward_it() {
+        let rules = offer_rules("tsun0", &range(), true);
+        assert_eq!(rules.len(), 3);
+        assert_eq!(
+            words(&rules[0].spec),
+            "-s 10.13.37.0/24 ! -o tsun0 -m comment --comment tsunagi-exit:tsun0:10.13.37.0/24 -j MASQUERADE"
+        );
+        assert_eq!((rules[0].table, rules[0].chain), ("nat", "POSTROUTING"));
+        assert_eq!(
+            words(&rules[1].spec),
+            "-i tsun0 -s 10.13.37.0/24 ! -o tsun0 -m comment --comment tsunagi-exit:tsun0:10.13.37.0/24 -j ACCEPT"
+        );
+        assert_eq!((rules[1].table, rules[1].chain), ("filter", "FORWARD"));
+        assert_eq!(
+            words(&rules[2].spec),
+            "-o tsun0 -d 10.13.37.0/24 -m conntrack --ctstate RELATED,ESTABLISHED -m comment --comment tsunagi-exit:tsun0:10.13.37.0/24 -j ACCEPT"
+        );
+        // Nothing may widen to every source or to the other direction.
+        for rule in &rules {
+            assert!(!words(&rule.spec).contains("0.0.0.0/0"));
+        }
+        assert!(words(&insert_args(&rules[1])).starts_with("-w 5 -t filter -I FORWARD 1 -i tsun0"));
+        assert!(words(&check_args(&rules[0])).starts_with("-w 5 -t nat -C POSTROUTING -s"));
+    }
+
+    #[test]
+    fn only_rules_with_our_tag_for_this_interface_are_selected() {
+        let listing = "\
+-P FORWARD DROP
+-A FORWARD -i tsun0 -s 10.13.37.0/24 ! -o tsun0 -m comment --comment tsunagi-exit:tsun0:10.13.37.0/24 -j ACCEPT
+-A FORWARD -i tsun1 -m comment --comment tsunagi-exit:tsun1:10.99.0.0/24 -j ACCEPT
+-A FORWARD -i tsun01 -m comment --comment tsunagi-exit:tsun01:10.5.0.0/24 -j ACCEPT
+-A FORWARD -m comment --comment \"allow tsunagi-exit:tsun0:x\" -j ACCEPT
+-A FORWARD -m comment --comment tsunagi:tsun0 -j ACCEPT
+-A INPUT -m comment --comment tsunagi-exit:tsun0:10.13.37.0/24 -j ACCEPT
+-A FORWARD -j ACCEPT
+";
+        let found = tagged_rules(listing, "FORWARD", &exit_tag_prefix("tsun0"));
+        assert_eq!(found.len(), 1, "{found:?}");
+        assert_eq!(found[0].tag, "tsunagi-exit:tsun0:10.13.37.0/24");
+        assert_eq!(
+            words(&delete_args("filter", "FORWARD", &found[0])),
+            "-w 5 -t filter -D FORWARD -i tsun0 -s 10.13.37.0/24 ! -o tsun0 -m comment --comment tsunagi-exit:tsun0:10.13.37.0/24 -j ACCEPT"
+        );
+        assert!(tagged_rules("", "FORWARD", "tsunagi-exit:tsun0:").is_empty());
+    }
+
+    /// A scripted `iptables` that remembers which rules it was given.
+    struct Fake {
+        calls: RefCell<Vec<String>>,
+        /// Rules present, as `-S` lines per `(table, chain)`.
+        listing: RefCell<Vec<(String, String)>>,
+        missing: bool,
+        check_ok: bool,
+        /// A kernel with no `comment` match, as small router builds have.
+        no_comment: bool,
+    }
+
+    impl Fake {
+        fn new(check_ok: bool) -> Self {
+            Self {
+                calls: RefCell::new(Vec::new()),
+                listing: RefCell::new(Vec::new()),
+                missing: false,
+                check_ok,
+                no_comment: false,
+            }
+        }
+
+        fn with_rule(self, table: &str, line: &str) -> Self {
+            self.listing
+                .borrow_mut()
+                .push((table.to_string(), line.to_string()));
+            self
+        }
+
+        fn run(&self, args: &[String]) -> Ran {
+            if self.missing {
+                return Ran::Missing;
+            }
+            let line = args.join(" ");
+            self.calls.borrow_mut().push(line.clone());
+            let table = args
+                .iter()
+                .position(|word| word == "-t")
+                .map(|at| args[at + 1].clone())
+                .unwrap_or_default();
+            let ok = |stdout: String| Ran::Exited {
+                success: true,
+                stdout,
+                stderr: String::new(),
+            };
+            if self.no_comment && line.contains("-m comment") {
+                return Ran::Exited {
+                    success: false,
+                    stdout: String::new(),
+                    stderr: "iptables: No chain/target/match by that name.".to_string(),
+                };
+            }
+            if line.contains(" -S ") {
+                let listing: Vec<String> = self
+                    .listing
+                    .borrow()
+                    .iter()
+                    .filter(|(t, _)| *t == table)
+                    .map(|(_, l)| l.clone())
+                    .collect();
+                return ok(listing.join("\n"));
+            }
+            if line.contains(" -C ") {
+                return Ran::Exited {
+                    success: self.check_ok,
+                    stdout: String::new(),
+                    stderr: String::new(),
+                };
+            }
+            ok(String::new())
+        }
+
+        fn verbs(&self, verb: &str) -> Vec<String> {
+            self.calls
+                .borrow()
+                .iter()
+                .filter(|call| call.contains(&format!(" {verb} ")))
+                .cloned()
+                .collect()
+        }
+    }
+
+    #[test]
+    fn a_kernel_without_the_comment_match_gets_the_rules_without_comments() {
+        let mut fake = Fake::new(false);
+        fake.no_comment = true;
+        let outcome = apply_offer(&|args| fake.run(args), "tsun0", &[range()]);
+        assert_eq!(outcome, vec![(range(), RuleOutcome::Applied)]);
+        let inserted = fake.verbs("-I");
+        assert_eq!(inserted.len(), 3, "{inserted:?}");
+        assert!(
+            inserted.iter().all(|call| !call.contains("comment")),
+            "{inserted:?}"
+        );
+    }
+
+    #[test]
+    fn rules_written_without_a_comment_are_ours_and_are_removed_with_them() {
+        // The way iptables prints them: its own option order.
+        let listing = "\
+-P FORWARD ACCEPT
+-A FORWARD -s 10.13.37.0/24 -i tsun0 ! -o tsun0 -j ACCEPT
+-A FORWARD -d 10.13.37.0/24 -o tsun0 -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT
+-A FORWARD -i tsun0 -j ACCEPT
+-A FORWARD -s 10.13.37.0/24 -i tsun1 ! -o tsun1 -j ACCEPT
+";
+        let found = tagged_rules(listing, "FORWARD", &exit_tag_prefix("tsun0"));
+        assert_eq!(found.len(), 2, "{found:?}");
+        assert!(
+            found
+                .iter()
+                .all(|rule| rule.tag == exit_tag("tsun0", &range()))
+        );
+        let nat = "-A POSTROUTING -s 10.13.37.0/24 ! -o tsun0 -j MASQUERADE\n";
+        assert_eq!(
+            tagged_rules(nat, "POSTROUTING", &exit_tag_prefix("tsun0")).len(),
+            1
+        );
+    }
+
+    #[test]
+    fn a_fresh_host_gets_the_three_rules() {
+        let fake = Fake::new(false);
+        let outcome = apply_offer(&|args| fake.run(args), "tsun0", &[range()]);
+        assert_eq!(outcome, vec![(range(), RuleOutcome::Applied)]);
+        let inserted = fake.verbs("-I");
+        assert_eq!(inserted.len(), 3, "{inserted:?}");
+        assert!(inserted[0].contains("-t nat -I POSTROUTING 1"));
+        assert!(fake.verbs("-D").is_empty());
+    }
+
+    #[test]
+    fn rules_already_in_place_are_left_alone() {
+        let tag = exit_tag("tsun0", &range());
+        let fake = Fake::new(true)
+            .with_rule(
+                "nat",
+                &format!("-A POSTROUTING -s 10.13.37.0/24 ! -o tsun0 -m comment --comment {tag} -j MASQUERADE"),
+            )
+            .with_rule("filter", &format!("-A FORWARD -i tsun0 -m comment --comment {tag} -j ACCEPT"))
+            .with_rule("filter", &format!("-A FORWARD -o tsun0 -m comment --comment {tag} -j ACCEPT"));
+        let outcome = apply_offer(&|args| fake.run(args), "tsun0", &[range()]);
+        assert_eq!(outcome, vec![(range(), RuleOutcome::Applied)]);
+        assert!(fake.verbs("-I").is_empty());
+        assert!(fake.verbs("-D").is_empty());
+    }
+
+    #[test]
+    fn a_stale_range_is_removed_and_a_half_installed_set_is_replaced() {
+        let old: Ipv4Range = "10.99.0.0/24".parse().unwrap();
+        let old_tag = exit_tag("tsun0", &old);
+        let tag = exit_tag("tsun0", &range());
+        let fake = Fake::new(true)
+            .with_rule(
+                "nat",
+                &format!(
+                    "-A POSTROUTING -s 10.99.0.0/24 -m comment --comment {old_tag} -j MASQUERADE"
+                ),
+            )
+            // Only one of the three for the current range.
+            .with_rule(
+                "filter",
+                &format!("-A FORWARD -i tsun0 -m comment --comment {tag} -j ACCEPT"),
+            )
+            // Somebody else's rule, which must survive.
+            .with_rule("filter", "-A FORWARD -i eth0 -j ACCEPT");
+        let outcome = apply_offer(&|args| fake.run(args), "tsun0", &[range()]);
+        assert_eq!(outcome, vec![(range(), RuleOutcome::Applied)]);
+        let deleted = fake.verbs("-D");
+        assert!(
+            deleted.iter().any(|call| call.contains(&old_tag)),
+            "{deleted:?}"
+        );
+        assert!(
+            deleted.iter().any(|call| call.contains(&tag)),
+            "{deleted:?}"
+        );
+        assert!(
+            deleted.iter().all(|call| !call.contains("eth0")),
+            "{deleted:?}"
+        );
+        assert_eq!(fake.verbs("-I").len(), 3);
+    }
+
+    #[test]
+    fn clearing_removes_only_our_rules_for_the_interface() {
+        let tag = exit_tag("tsun0", &range());
+        let other = exit_tag("tsun1", &range());
+        let fake = Fake::new(true)
+            .with_rule(
+                "nat",
+                &format!("-A POSTROUTING -m comment --comment {tag} -j MASQUERADE"),
+            )
+            .with_rule(
+                "nat",
+                &format!("-A POSTROUTING -m comment --comment {other} -j MASQUERADE"),
+            )
+            .with_rule("filter", "-A FORWARD -j ACCEPT");
+        clear_offer(&|args| fake.run(args), "tsun0");
+        let deleted = fake.verbs("-D");
+        assert_eq!(deleted.len(), 1, "{deleted:?}");
+        assert!(deleted[0].contains(&tag));
+    }
+
+    #[test]
+    fn a_missing_iptables_is_a_failure_that_says_what_to_do() {
+        let mut fake = Fake::new(false);
+        fake.missing = true;
+        let outcome = apply_offer(&|args| fake.run(args), "tsun0", &[range()]);
+        let RuleOutcome::Failed(reason) = &outcome[0].1 else {
+            panic!("{outcome:?}");
+        };
+        assert!(reason.contains("iptables not found"), "{reason}");
+        assert!(reason.contains("10.13.37.0/24"), "{reason}");
+        // Nothing wanted and nothing to run is not a failure of anything.
+        assert!(apply_offer(&|args| fake.run(args), "tsun0", &[]).is_empty());
+    }
+
+    #[test]
+    fn forwarding_is_read_per_interface_then_globally_and_never_written() {
+        let files = |per: Option<&'static str>, global: Option<&'static str>| {
+            move |path: &str| match path {
+                "/proc/sys/net/ipv4/conf/tsun0/forwarding" => per.map(str::to_string),
+                "/proc/sys/net/ipv4/ip_forward" => global.map(str::to_string),
+                _ => None,
+            }
+        };
+        assert_eq!(
+            forwarding_state(files(Some("1\n"), Some("0\n")), "tsun0"),
+            Some(true)
+        );
+        assert_eq!(
+            forwarding_state(files(Some("0\n"), Some("1\n")), "tsun0"),
+            Some(false)
+        );
+        assert_eq!(
+            forwarding_state(files(None, Some("1\n")), "tsun0"),
+            Some(true)
+        );
+        assert_eq!(forwarding_state(files(None, None), "tsun0"), None);
+        assert_eq!(forwarding_state(files(Some("junk"), None), "tsun0"), None);
+        // A name that would leave the directory is not looked up.
+        assert_eq!(forwarding_state(files(Some("1"), None), "../../x"), None);
+    }
+
+    #[test]
+    fn the_effective_uid_is_the_second_field() {
+        let status = "Name:\ttsunagi\nUid:\t1001\t1002\t1001\t1001\nGid:\t5\t5\t5\t5\n";
+        assert_eq!(parse_euid(status), Some(1002));
+        assert_eq!(parse_euid("Name:\tx\n"), None);
+    }
+
+    #[test]
+    fn a_login_session_is_refused_and_a_service_is_not() {
+        let reason = client_refusal(Some("/run/user/1000")).unwrap();
+        assert!(reason.contains("system service"), "{reason}");
+        assert!(client_refusal(None).is_none());
+        assert!(client_refusal(Some("")).is_none());
+    }
+}

crates/tsunagi-core/src/overlay/hostrules/macos.rs

@@ -19,6 +19,10 @@
 
 use crate::BoxFuture;
 
+use std::sync::{Arc, Mutex};
+
+use super::exit::{ExitHostPlan, ExitHostReport, ExitHostRules};
+use super::macos_exit::{apply_plan, clear_all, run_tool};
 use super::{BroadcastHostRules, BroadcastRulesPlan, BroadcastRulesReport, RuleOutcome};
 
 /// The limited-broadcast destination routed through the overlay interface.
@@ -60,14 +64,19 @@ fn firewall_todo(plan: &BroadcastRulesPlan) -> String {
     )
 }
 
-/// The macOS implementation: `route` for the route, no firewall yet.
+/// The macOS implementation: `route` for the route, no firewall yet, and
+/// `pf` plus `route` for exit nodes (see [`super::macos_exit`]).
 #[derive(Debug, Default)]
-pub struct MacosHostRules;
+pub struct MacosHostRules {
+    /// The reference `pfctl -E` handed out, held while exit-node rules need
+    /// `pf` on and released when they are removed.
+    pub(super) pf_token: Arc<Mutex<Option<String>>>,
+}
 
 impl MacosHostRules {
     /// Creates the host rules.
     pub fn new() -> Self {
-        Self
+        Self::default()
     }
 
     /// Installs the route, replacing one this agent added earlier so the call
@@ -82,11 +91,46 @@ impl MacosHostRules {
     }
 }
 
+impl ExitHostRules for MacosHostRules {
+    fn apply<'a>(&'a self, plan: &'a ExitHostPlan) -> BoxFuture<'a, ExitHostReport> {
+        Box::pin(async move {
+            let job_plan = plan.clone();
+            let token = Arc::clone(&self.pf_token);
+            tokio::task::spawn_blocking(move || apply_plan(&run_tool, &token, &job_plan))
+                .await
+                .unwrap_or_else(|err| {
+                    let failed = RuleOutcome::Failed(format!("the task failed: {err}"));
+                    ExitHostReport {
+                        offer: plan
+                            .offer
+                            .iter()
+                            .map(|range| (*range, failed.clone()))
+                            .collect(),
+                        forwarding: None,
+                        client: plan.client.then_some(failed),
+                    }
+                })
+        })
+    }
+
+    fn clear<'a>(&'a self, interface: &'a str) -> BoxFuture<'a, ()> {
+        Box::pin(async move {
+            let name = interface.to_string();
+            let token = Arc::clone(&self.pf_token);
+            let _ = tokio::task::spawn_blocking(move || clear_all(&run_tool, &token, &name)).await;
+        })
+    }
+}
+
 impl BroadcastHostRules for MacosHostRules {
     fn name(&self) -> &str {
         "route"
     }
 
+    fn exit_rules(&self) -> Option<&dyn ExitHostRules> {
+        Some(self)
+    }
+
     fn apply<'a>(&'a self, plan: &'a BroadcastRulesPlan) -> BoxFuture<'a, BroadcastRulesReport> {
         Box::pin(async move {
             let route = self.set_route(plan.interface.clone()).await;

crates/tsunagi-core/src/overlay/hostrules/macos_exit.rs

@@ -0,0 +1,915 @@
+//! Exit-node host rules on macOS: a `pf` anchor and `route` entries.
+//!
+//! Compiled on every platform so the rule text and the parsers are tested
+//! everywhere; only `MacosHostRules` runs them, and only on macOS.
+//!
+//! # Offering
+//!
+//! Per offered range, in the anchor `com.apple/tsunagi-exit-<if>`:
+//!
+//! ```text
+//! nat on <egress> inet from <range> to any -> (<egress>)
+//! pass in quick on <if> inet from <range> to ! <range>
+//! ```
+//!
+//! The anchor lives under `com.apple/` on purpose: the stock `/etc/pf.conf`
+//! evaluates `nat-anchor "com.apple/*"` and `anchor "com.apple/*"`, so the
+//! rules take effect without editing the user's ruleset. `pf` cannot say
+//! "every interface but one" in a translation address, so the egress is the
+//! interface of the default route **when the rules are applied**; after the
+//! default route moves (Wi-Fi to Ethernet) the rules are re-applied by
+//! switching the exit node off and on, or restarting the agent.
+//!
+//! The kernel's `net.inet.ip.forwarding` is only read, never written: it
+//! changes how the whole host behaves, which is the owner's decision.
+//!
+//! # Using
+//!
+//! macOS has no `uidrange` policy routing, and the agent is root, so the
+//! Linux scheme does not carry over. Instead:
+//!
+//! ```text
+//! route add -net 0.0.0.0/1   -interface <if>
+//! route add -net 128.0.0.0/1 -interface <if>
+//! pass out quick on <if> route-to (<egress> <gateway>) inet proto { tcp udp }
+//!     from any to ! <overlay ranges> user <agent uid>
+//! nat on <egress> inet from (<if>) to any -> (<egress>)
+//! ```
+//!
+//! The two halves outrank the default route without replacing it, and every
+//! more specific route (LAN, another VPN) keeps working. The `route-to` rule
+//! sends the *agent's own* traffic — QUIC, relay, DHT, which would otherwise
+//! loop into the tunnel it carries — back out the physical interface, and the
+//! translation gives it that interface's address, since an unbound socket
+//! picked the overlay address when the route pointed at the overlay. Like the
+//! Linux exemption this is by user id, so anything else running as root also
+//! bypasses the tunnel.
+//!
+//! IPv6 is blocked while an exit node is in use, as on Linux: `::/1` and
+//! `8000::/1` are rejecting routes, so applications fall back to IPv4 at once
+//! instead of leaking.
+//!
+//! Every object is derived from local state and the interface the agent owns;
+//! none of it comes from a peer.
+
+use std::net::Ipv4Addr;
+use std::sync::Mutex;
+
+use crate::state::Ipv4Range;
+
+use super::RuleOutcome;
+use super::exit::{ExitHostPlan, ExitHostReport};
+
+/// The programs this module runs, always by absolute path.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(super) enum Tool {
+    Route,
+    Pfctl,
+    Sysctl,
+    Id,
+}
+
+impl Tool {
+    fn path(self) -> &'static str {
+        match self {
+            Self::Route => "/sbin/route",
+            Self::Pfctl => "/sbin/pfctl",
+            Self::Sysctl => "/usr/sbin/sysctl",
+            Self::Id => "/usr/bin/id",
+        }
+    }
+}
+
+/// What running a tool came to.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(super) enum Ran {
+    /// The program is not there.
+    Missing,
+    /// It ran.
+    Exited {
+        success: bool,
+        stdout: String,
+        stderr: String,
+    },
+}
+
+/// Runs a tool with optional standard input; injectable so the logic is
+/// tested without touching the host.
+pub(super) type Run<'a> = &'a dyn Fn(Tool, &[String], Option<&str>) -> Ran;
+
+/// Runs a real tool. Blocking: callers use `spawn_blocking`.
+pub(super) fn run_tool(tool: Tool, args: &[String], stdin: Option<&str>) -> Ran {
+    use std::io::Write;
+    use std::process::{Command, Stdio};
+
+    let mut command = Command::new(tool.path());
+    command
+        .args(args)
+        .stdin(if stdin.is_some() {
+            Stdio::piped()
+        } else {
+            Stdio::null()
+        })
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped());
+    let mut child = match command.spawn() {
+        Ok(child) => child,
+        Err(err) if err.kind() == std::io::ErrorKind::NotFound => return Ran::Missing,
+        Err(err) => {
+            return Ran::Exited {
+                success: false,
+                stdout: String::new(),
+                stderr: format!("could not run {}: {err}", tool.path()),
+            };
+        }
+    };
+    if let (Some(text), Some(mut pipe)) = (stdin, child.stdin.take()) {
+        // A write error shows up as the tool's own failure below.
+        let _ = pipe.write_all(text.as_bytes());
+    }
+    match child.wait_with_output() {
+        Ok(output) => Ran::Exited {
+            success: output.status.success(),
+            stdout: String::from_utf8_lossy(&output.stdout).into_owned(),
+            stderr: String::from_utf8_lossy(&output.stderr).into_owned(),
+        },
+        Err(err) => Ran::Exited {
+            success: false,
+            stdout: String::new(),
+            stderr: format!("could not run {}: {err}", tool.path()),
+        },
+    }
+}
+
+fn owned(words: &[&str]) -> Vec<String> {
+    words.iter().map(|word| word.to_string()).collect()
+}
+
+/// A name that is safe in a `pf` rule, an anchor path and a table name.
+fn safe_name(name: &str) -> bool {
+    !name.is_empty() && name.len() <= 32 && name.chars().all(|c| c.is_ascii_alphanumeric())
+}
+
+/// The anchor holding every rule of one interface.
+fn anchor_name(interface: &str) -> Result<String, String> {
+    if safe_name(interface) {
+        Ok(format!("com.apple/tsunagi-exit-{interface}"))
+    } else {
+        Err(format!(
+            "`{interface}` is not an interface name this agent can write a pf rule for"
+        ))
+    }
+}
+
+/// The default route as `route -n get default` reports it.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(super) struct DefaultRoute {
+    pub interface: String,
+    pub gateway: Option<Ipv4Addr>,
+}
+
+/// Reads `interface:` and `gateway:` out of `route -n get default`.
+fn parse_default_route(text: &str) -> Option<DefaultRoute> {
+    let field = |name: &str| {
+        text.lines().find_map(|line| {
+            let (key, value) = line.split_once(':')?;
+            (key.trim() == name).then(|| value.trim().to_string())
+        })
+    };
+    let interface = field("interface").filter(|name| safe_name(name))?;
+    let gateway = field("gateway").and_then(|value| value.parse().ok());
+    Some(DefaultRoute { interface, gateway })
+}
+
+fn failure(stderr: &str, stdout: &str) -> String {
+    let text = if stderr.trim().is_empty() {
+        stdout.trim()
+    } else {
+        stderr.trim()
+    };
+    if text.is_empty() {
+        "the command failed without saying why".to_string()
+    } else {
+        text.to_string()
+    }
+}
+
+/// Runs a tool and turns a failure into a sentence a person can act on.
+fn run_ok(
+    run: Run<'_>,
+    tool: Tool,
+    args: &[String],
+    stdin: Option<&str>,
+) -> Result<String, String> {
+    match run(tool, args, stdin) {
+        Ran::Missing => Err(format!("{} not found", tool.path())),
+        Ran::Exited {
+            success: true,
+            stdout,
+            ..
+        } => Ok(stdout),
+        Ran::Exited { stderr, stdout, .. } => Err(format!(
+            "{} {} failed: {}",
+            tool.path(),
+            args.join(" "),
+            failure(&stderr, &stdout)
+        )),
+    }
+}
+
+/// The route traffic leaves by now, which is the egress for translation and
+/// for the agent's own sockets. Read *before* the overlay routes are added.
+fn default_route(run: Run<'_>, overlay: &str) -> Result<DefaultRoute, String> {
+    let out = run_ok(run, Tool::Route, &owned(&["-n", "get", "default"]), None)
+        .map_err(|why| format!("cannot find the default route: {why}"))?;
+    let route = parse_default_route(&out)
+        .ok_or_else(|| "the host has no default route to send traffic out of".to_string())?;
+    if route.interface == overlay {
+        return Err(format!(
+            "the default route already goes through `{overlay}`"
+        ));
+    }
+    Ok(route)
+}
+
+/// Whether the kernel forwards IPv4. Read only.
+fn forwarding_state(run: Run<'_>) -> Option<bool> {
+    let out = run_ok(
+        run,
+        Tool::Sysctl,
+        &owned(&["-n", "net.inet.ip.forwarding"]),
+        None,
+    )
+    .ok()?;
+    match out.trim() {
+        "1" => Some(true),
+        "0" => Some(false),
+        _ => None,
+    }
+}
+
+/// The effective user id of this process, from `id -u`.
+fn agent_uid(run: Run<'_>) -> Result<u32, String> {
+    run_ok(run, Tool::Id, &owned(&["-u"]), None)
+        .ok()
+        .and_then(|out| out.trim().parse().ok())
+        .ok_or_else(|| "cannot tell which user this agent runs as".to_string())
+}
+
+/// What the using side adds to the rules.
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct ClientRules<'a> {
+    uid: u32,
+    /// Every overlay range: the agent's own traffic *to* those still goes
+    /// through the interface.
+    overlay: &'a [Ipv4Range],
+}
+
+/// The text of the anchor: translation first, filtering after, which is the
+/// order `pf` insists on.
+fn pf_rules(
+    interface: &str,
+    egress: &DefaultRoute,
+    offer: &[Ipv4Range],
+    client: Option<&ClientRules<'_>>,
+) -> String {
+    let out = &egress.interface;
+    let mut nat = Vec::new();
+    let mut filter = Vec::new();
+    for range in offer {
+        nat.push(format!("nat on {out} inet from {range} to any -> ({out})"));
+        filter.push(format!(
+            "pass in quick on {interface} inet from {range} to ! {range}"
+        ));
+    }
+    let mut tables = Vec::new();
+    if let Some(client) = client {
+        nat.push(format!(
+            "nat on {out} inet from ({interface}) to any -> ({out})"
+        ));
+        let target = if client.overlay.is_empty() {
+            "any".to_string()
+        } else {
+            let ranges: Vec<String> = client.overlay.iter().map(|r| r.to_string()).collect();
+            // A table, because `! { a, b }` expands to one rule per element
+            // in older `pf`, which matches everything.
+            tables.push(format!(
+                "table <tsunagi_overlay_{interface}> const {{ {} }}",
+                ranges.join(", ")
+            ));
+            format!("! <tsunagi_overlay_{interface}>")
+        };
+        let via = match egress.gateway {
+            Some(gateway) => format!("({out} {gateway})"),
+            None => out.clone(),
+        };
+        filter.push(format!(
+            "pass out quick on {interface} route-to {via} inet proto {{ tcp udp }} \
+             from any to {target} user {}",
+            client.uid
+        ));
+    }
+    tables
+        .into_iter()
+        .chain(nat)
+        .chain(filter)
+        .collect::<Vec<_>>()
+        .join("\n")
+        + "\n"
+}
+
+/// Turns `pf` on if nobody has, holding the reference `pfctl` hands out so it
+/// can be released when the agent is done. One reference at most.
+fn acquire_pf(run: Run<'_>, slot: &Mutex<Option<String>>) -> Result<(), String> {
+    if lock(slot).is_some() {
+        return Ok(());
+    }
+    match run(Tool::Pfctl, &owned(&["-E"]), None) {
+        Ran::Missing => Err(format!("{} not found", Tool::Pfctl.path())),
+        Ran::Exited {
+            success,
+            stdout,
+            stderr,
+        } => {
+            // `pfctl -E` reports `Token : <n>` on stderr, and also says so
+            // when pf is already enabled.
+            let token = stdout.lines().chain(stderr.lines()).find_map(parse_token);
+            if !success && token.is_none() {
+                return Err(format!("cannot enable pf: {}", failure(&stderr, &stdout)));
+            }
+            *lock(slot) = token;
+            Ok(())
+        }
+    }
+}
+
+fn parse_token(line: &str) -> Option<String> {
+    let (key, value) = line.split_once(':')?;
+    let value = value.trim();
+    (key.trim().eq_ignore_ascii_case("token")
+        && !value.is_empty()
+        && value.chars().all(|c| c.is_ascii_digit()))
+    .then(|| value.to_string())
+}
+
+fn release_pf(run: Run<'_>, slot: &Mutex<Option<String>>) {
+    if let Some(token) = lock(slot).take()
+        && let Err(why) = run_ok(run, Tool::Pfctl, &["-X".to_string(), token], None)
+    {
+        tracing::debug!(%why, "cannot release the pf reference");
+    }
+}
+
+fn lock<T>(mutex: &Mutex<T>) -> std::sync::MutexGuard<'_, T> {
+    match mutex.lock() {
+        Ok(guard) => guard,
+        Err(poisoned) => poisoned.into_inner(),
+    }
+}
+
+fn flush_args(anchor: &str) -> Vec<String> {
+    owned(&["-q", "-a", anchor, "-F", "all"])
+}
+
+fn load_args(anchor: &str) -> Vec<String> {
+    owned(&["-q", "-a", anchor, "-f", "-"])
+}
+
+/// The two halves that out-rank the default route.
+const HALVES: [&str; 2] = ["0.0.0.0/1", "128.0.0.0/1"];
+/// The IPv6 halves, made unreachable.
+const HALVES_V6: [&str; 2] = ["::/1", "8000::/1"];
+
+fn route_add_args(half: &str, interface: &str) -> Vec<String> {
+    owned(&["-q", "-n", "add", "-net", half, "-interface", interface])
+}
+
+fn route_del_args(half: &str, interface: &str) -> Vec<String> {
+    owned(&["-q", "-n", "delete", "-net", half, "-interface", interface])
+}
+
+fn route_add_v6_args(half: &str) -> Vec<String> {
+    owned(&["-q", "-n", "add", "-inet6", "-net", half, "::1", "-reject"])
+}
+
+fn route_del_v6_args(half: &str) -> Vec<String> {
+    owned(&["-q", "-n", "delete", "-inet6", "-net", half, "::1"])
+}
+
+/// Takes away the overlay default routes. Best effort: what is not there is
+/// the state wanted.
+fn clear_routes(run: Run<'_>, interface: &str) {
+    for half in HALVES {
+        let _ = run(Tool::Route, &route_del_args(half, interface), None);
+    }
+    for half in HALVES_V6 {
+        let _ = run(Tool::Route, &route_del_v6_args(half), None);
+    }
+}
+
+fn set_routes(run: Run<'_>, interface: &str) -> Result<(), String> {
+    clear_routes(run, interface);
+    for half in HALVES {
+        if let Err(why) = run_ok(run, Tool::Route, &route_add_args(half, interface), None) {
+            clear_routes(run, interface);
+            return Err(why);
+        }
+    }
+    for half in HALVES_V6 {
+        // A host without IPv6 has nothing to block; not a failure.
+        if let Err(why) = run_ok(run, Tool::Route, &route_add_v6_args(half), None) {
+            tracing::debug!(%why, "cannot block IPv6 for the exit node");
+        }
+    }
+    Ok(())
+}
+
+/// Makes the host match the plan.
+pub(super) fn apply_plan(
+    run: Run<'_>,
+    token: &Mutex<Option<String>>,
+    plan: &ExitHostPlan,
+) -> ExitHostReport {
+    let forwarding = if plan.offer.is_empty() {
+        None
+    } else {
+        forwarding_state(run)
+    };
+    let outcome = apply_rules(run, token, plan);
+    let verdict = |ok: bool, why: &str| {
+        if ok {
+            RuleOutcome::Applied
+        } else {
+            RuleOutcome::Failed(why.to_string())
+        }
+    };
+    match outcome {
+        Ok(()) => ExitHostReport {
+            offer: plan
+                .offer
+                .iter()
+                .map(|range| (*range, RuleOutcome::Applied))
+                .collect(),
+            forwarding,
+            client: plan.client.then_some(RuleOutcome::Applied),
+        },
+        Err(why) => ExitHostReport {
+            offer: plan
+                .offer
+                .iter()
+                .map(|range| (*range, verdict(false, &why)))
+                .collect(),
+            forwarding,
+            client: plan.client.then(|| verdict(false, &why)),
+        },
+    }
+}
+
+fn apply_rules(
+    run: Run<'_>,
+    token: &Mutex<Option<String>>,
+    plan: &ExitHostPlan,
+) -> Result<(), String> {
+    let interface = plan.interface.as_str();
+    let anchor = anchor_name(interface)?;
+    let egress = default_route(run, interface)?;
+    let uid = if plan.client {
+        Some(agent_uid(run)?)
+    } else {
+        None
+    };
+    let client = uid.map(|uid| ClientRules {
+        uid,
+        overlay: &plan.overlay,
+    });
+    let rules = pf_rules(interface, &egress, &plan.offer, client.as_ref());
+
+    acquire_pf(run, token)?;
+    run_ok(run, Tool::Pfctl, &load_args(&anchor), Some(&rules))
+        .map_err(|why| format!("cannot load the pf rules: {why}"))?;
+    // The routes come after the rules that keep the agent's own traffic off
+    // them: the other order would loop for as long as it takes.
+    if plan.client {
+        set_routes(run, interface)?;
+    } else {
+        clear_routes(run, interface);
+    }
+    Ok(())
+}
+
+/// Removes everything this agent put there for the interface.
+pub(super) fn clear_all(run: Run<'_>, token: &Mutex<Option<String>>, interface: &str) {
+    clear_routes(run, interface);
+    if let Ok(anchor) = anchor_name(interface) {
+        // Flushing an anchor nothing was ever loaded into is not an error
+        // worth reporting.
+        if let Err(why) = run_ok(run, Tool::Pfctl, &flush_args(&anchor), None) {
+            tracing::debug!(%why, "cannot flush the exit node pf anchor");
+        }
+    }
+    release_pf(run, token);
+}
+
+#[cfg(test)]
+mod tests {
+    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
+
+    use std::cell::RefCell;
+
+    use super::*;
+
+    fn range() -> Ipv4Range {
+        "10.13.37.0/24".parse().unwrap()
+    }
+
+    const DEFAULT_ROUTE: &str = "   route to: default\n\
+destination: default\n\
+       mask: default\n\
+    gateway: 192.168.1.1\n\
+  interface: en0\n\
+      flags: <UP,GATEWAY,DONE,STATIC,PRCLONING,GLOBAL>\n";
+
+    fn egress() -> DefaultRoute {
+        DefaultRoute {
+            interface: "en0".into(),
+            gateway: Some(Ipv4Addr::new(192, 168, 1, 1)),
+        }
+    }
+
+    /// A scripted host that records every call.
+    struct Fake {
+        calls: RefCell<Vec<String>>,
+        stdins: RefCell<Vec<String>>,
+        default_route: Option<String>,
+        forwarding: &'static str,
+        pf_missing: bool,
+        pf_load_fails: bool,
+        route_add_fails: bool,
+        pf_enable_output: &'static str,
+    }
+
+    impl Fake {
+        fn new() -> Self {
+            Self {
+                calls: RefCell::new(Vec::new()),
+                stdins: RefCell::new(Vec::new()),
+                default_route: Some(DEFAULT_ROUTE.to_string()),
+                forwarding: "1\n",
+                pf_missing: false,
+                pf_load_fails: false,
+                route_add_fails: false,
+                pf_enable_output: "pf enabled\nToken : 4242\n",
+            }
+        }
+
+        fn run(&self, tool: Tool, args: &[String], stdin: Option<&str>) -> Ran {
+            let line = format!("{:?} {}", tool, args.join(" "));
+            self.calls.borrow_mut().push(line);
+            if let Some(text) = stdin {
+                self.stdins.borrow_mut().push(text.to_string());
+            }
+            let ok = |stdout: &str, stderr: &str| Ran::Exited {
+                success: true,
+                stdout: stdout.to_string(),
+                stderr: stderr.to_string(),
+            };
+            let fail = |why: &str| Ran::Exited {
+                success: false,
+                stdout: String::new(),
+                stderr: why.to_string(),
+            };
+            match tool {
+                Tool::Id => ok("0\n", ""),
+                Tool::Sysctl => ok(self.forwarding, ""),
+                Tool::Route if args.first().map(String::as_str) == Some("-n") => {
+                    match &self.default_route {
+                        Some(text) => ok(text, ""),
+                        None => fail("route: writing to routing socket: not in table"),
+                    }
+                }
+                Tool::Route if args.contains(&"add".to_string()) && self.route_add_fails => {
+                    fail("route: writing to routing socket: File exists")
+                }
+                Tool::Route => ok("", ""),
+                Tool::Pfctl if self.pf_missing => Ran::Missing,
+                Tool::Pfctl if args == ["-E"] => ok("", self.pf_enable_output),
+                Tool::Pfctl if args.contains(&"-f".to_string()) && self.pf_load_fails => {
+                    fail("pfctl: Syntax error")
+                }
+                Tool::Pfctl => ok("", ""),
+            }
+        }
+
+        fn calls(&self) -> Vec<String> {
+            self.calls.borrow().clone()
+        }
+
+        fn position(&self, needle: &str) -> Option<usize> {
+            self.calls.borrow().iter().position(|c| c.contains(needle))
+        }
+
+        fn count(&self, needle: &str) -> usize {
+            self.calls
+                .borrow()
+                .iter()
+                .filter(|c| c.contains(needle))
+                .count()
+        }
+    }
+
+    fn plan(offer: bool, client: bool) -> ExitHostPlan {
+        ExitHostPlan {
+            interface: "utun5".into(),
+            offer: if offer { vec![range()] } else { Vec::new() },
+            client,
+            overlay: vec![range()],
+            ..Default::default()
+        }
+    }
+
+    #[test]
+    fn the_default_route_is_read_from_route_output() {
+        assert_eq!(parse_default_route(DEFAULT_ROUTE), Some(egress()));
+        // A point-to-point default has no gateway line to use.
+        let ppp = "destination: default\n  interface: ppp0\n";
+        assert_eq!(
+            parse_default_route(ppp),
+            Some(DefaultRoute {
+                interface: "ppp0".into(),
+                gateway: None
+            })
+        );
+        assert_eq!(parse_default_route("route: not in table"), None);
+        // An interface name that is not plain letters and digits never ends
+        // up in a rule.
+        assert_eq!(parse_default_route("interface: en0; pass all\n"), None);
+    }
+
+    #[test]
+    fn the_anchor_is_under_com_apple_and_only_for_plain_names() {
+        assert_eq!(
+            anchor_name("utun5").unwrap(),
+            "com.apple/tsunagi-exit-utun5"
+        );
+        assert!(anchor_name("").is_err());
+        assert!(anchor_name("utun5 pass all").is_err());
+        assert!(anchor_name("../x").is_err());
+    }
+
+    #[test]
+    fn offering_translates_the_range_and_admits_it_in() {
+        let text = pf_rules("utun5", &egress(), &[range()], None);
+        assert_eq!(
+            text,
+            "nat on en0 inet from 10.13.37.0/24 to any -> (en0)\n\
+             pass in quick on utun5 inet from 10.13.37.0/24 to ! 10.13.37.0/24\n"
+        );
+        // Translation precedes filtering, as pf requires.
+        assert!(text.find("nat on").unwrap() < text.find("pass in").unwrap());
+    }
+
+    #[test]
+    fn using_sends_the_agents_own_traffic_back_out_the_physical_interface() {
+        let other: Ipv4Range = "10.99.0.0/16".parse().unwrap();
+        let overlay = [range(), other];
+        let client = ClientRules {
+            uid: 0,
+            overlay: &overlay,
+        };
+        let text = pf_rules("utun5", &egress(), &[], Some(&client));
+        assert!(
+            text.starts_with(
+                "table <tsunagi_overlay_utun5> const { 10.13.37.0/24, 10.99.0.0/16 }\n"
+            ),
+            "{text}"
+        );
+        assert!(
+            text.contains("nat on en0 inet from (utun5) to any -> (en0)\n"),
+            "{text}"
+        );
+        assert!(
+            text.contains(
+                "pass out quick on utun5 route-to (en0 192.168.1.1) inet proto { tcp udp } \
+                 from any to ! <tsunagi_overlay_utun5> user 0\n"
+            ),
+            "{text}"
+        );
+        // Only the agent's user, and only what is not the overlay.
+        assert!(!text.contains("from any to any"));
+
+        let direct = DefaultRoute {
+            interface: "ppp0".into(),
+            gateway: None,
+        };
+        let text = pf_rules(
+            "utun5",
+            &direct,
+            &[],
+            Some(&ClientRules {
+                uid: 501,
+                overlay: &[],
+            }),
+        );
+        assert!(text.contains("route-to ppp0 inet"), "{text}");
+        assert!(text.contains("to any user 501"), "{text}");
+        assert!(!text.contains("table"), "{text}");
+    }
+
+    #[test]
+    fn the_overlay_default_routes_are_halves_and_ipv6_is_rejected() {
+        assert_eq!(
+            route_add_args("0.0.0.0/1", "utun5").join(" "),
+            "-q -n add -net 0.0.0.0/1 -interface utun5"
+        );
+        assert_eq!(
+            route_del_args("128.0.0.0/1", "utun5").join(" "),
+            "-q -n delete -net 128.0.0.0/1 -interface utun5"
+        );
+        assert_eq!(
+            route_add_v6_args("8000::/1").join(" "),
+            "-q -n add -inet6 -net 8000::/1 ::1 -reject"
+        );
+        assert_eq!(
+            route_del_v6_args("::/1").join(" "),
+            "-q -n delete -inet6 -net ::/1 ::1"
+        );
+    }
+
+    #[test]
+    fn the_pf_token_is_found_in_either_stream() {
+        assert_eq!(parse_token("Token : 1234"), Some("1234".into()));
+        assert_eq!(parse_token("token: 9"), Some("9".into()));
+        assert_eq!(parse_token("pf enabled"), None);
+        assert_eq!(parse_token("Token : x; rm"), None);
+    }
+
+    #[test]
+    fn offering_loads_the_anchor_and_reads_but_never_writes_forwarding() {
+        let fake = Fake::new();
+        let token = Mutex::new(None);
+        let report = apply_plan(&|t, a, s| fake.run(t, a, s), &token, &plan(true, false));
+        assert_eq!(report.offer, vec![(range(), RuleOutcome::Applied)]);
+        assert_eq!(report.forwarding, Some(true));
+        assert_eq!(report.client, None);
+        let calls = fake.calls();
+        assert!(
+            calls
+                .iter()
+                .any(|c| c == "Pfctl -q -a com.apple/tsunagi-exit-utun5 -f -"),
+            "{calls:?}"
+        );
+        assert_eq!(
+            fake.stdins.borrow()[0],
+            "nat on en0 inet from 10.13.37.0/24 to any -> (en0)\n\
+             pass in quick on utun5 inet from 10.13.37.0/24 to ! 10.13.37.0/24\n"
+        );
+        // sysctl is only ever asked, never told.
+        assert!(
+            calls
+                .iter()
+                .filter(|c| c.starts_with("Sysctl"))
+                .all(|c| c == "Sysctl -n net.inet.ip.forwarding"),
+            "{calls:?}"
+        );
+        // No client routes were added for an offer alone.
+        assert_eq!(fake.count(" add "), 0);
+        assert_eq!(token.lock().unwrap().as_deref(), Some("4242"));
+    }
+
+    #[test]
+    fn forwarding_off_is_reported_and_unreadable_is_none() {
+        let mut fake = Fake::new();
+        fake.forwarding = "0\n";
+        let token = Mutex::new(None);
+        let report = apply_plan(&|t, a, s| fake.run(t, a, s), &token, &plan(true, false));
+        assert_eq!(report.forwarding, Some(false));
+        fake.forwarding = "junk";
+        let report = apply_plan(&|t, a, s| fake.run(t, a, s), &token, &plan(true, false));
+        assert_eq!(report.forwarding, None);
+    }
+
+    #[test]
+    fn the_client_rules_are_loaded_before_the_routes_that_need_them() {
+        let fake = Fake::new();
+        let token = Mutex::new(None);
+        let report = apply_plan(&|t, a, s| fake.run(t, a, s), &token, &plan(false, true));
+        assert_eq!(report.client, Some(RuleOutcome::Applied));
+        assert!(report.offer.is_empty());
+        let load = fake.position("-f -").unwrap();
+        let add = fake.position(" add -net 0.0.0.0/1").unwrap();
+        assert!(load < add, "{:?}", fake.calls());
+        assert!(fake.position("add -net 128.0.0.0/1").is_some());
+        assert!(fake.position("-inet6 -net ::/1 ::1 -reject").is_some());
+        assert!(fake.stdins.borrow()[0].contains("user 0"));
+        // The default route was read before any overlay route existed.
+        assert!(fake.position("-n get default").unwrap() < add);
+    }
+
+    #[test]
+    fn no_routes_are_added_when_the_rules_did_not_load() {
+        let mut fake = Fake::new();
+        fake.pf_load_fails = true;
+        let token = Mutex::new(None);
+        let report = apply_plan(&|t, a, s| fake.run(t, a, s), &token, &plan(true, true));
+        let Some(RuleOutcome::Failed(why)) = report.client else {
+            panic!("{report:?}");
+        };
+        assert!(why.contains("cannot load the pf rules"), "{why}");
+        assert!(why.contains("Syntax error"), "{why}");
+        assert!(matches!(report.offer[0].1, RuleOutcome::Failed(_)));
+        // Nothing sent the host's traffic into a tunnel it could not exempt
+        // the agent from.
+        assert_eq!(fake.count(" add "), 0);
+    }
+
+    #[test]
+    fn a_failing_route_is_a_failure_and_leaves_nothing_behind() {
+        let mut fake = Fake::new();
+        fake.route_add_fails = true;
+        let token = Mutex::new(None);
+        let report = apply_plan(&|t, a, s| fake.run(t, a, s), &token, &plan(false, true));
+        let Some(RuleOutcome::Failed(why)) = report.client else {
+            panic!("{report:?}");
+        };
+        assert!(why.contains("File exists"), "{why}");
+        // The cleanup after the failed add removed whatever did land.
+        let last_add = fake
+            .calls()
+            .iter()
+            .rposition(|c| c.contains(" add "))
+            .unwrap();
+        assert!(
+            fake.calls()[last_add..]
+                .iter()
+                .any(|c| c.contains("delete"))
+        );
+    }
+
+    #[test]
+    fn a_missing_pfctl_or_default_route_says_what_is_wrong() {
+        let mut fake = Fake::new();
+        fake.pf_missing = true;
+        let token = Mutex::new(None);
+        let report = apply_plan(&|t, a, s| fake.run(t, a, s), &token, &plan(true, false));
+        let RuleOutcome::Failed(why) = &report.offer[0].1 else {
+            panic!("{report:?}");
+        };
+        assert!(why.contains("/sbin/pfctl not found"), "{why}");
+
+        let mut fake = Fake::new();
+        fake.default_route = None;
+        let report = apply_plan(&|t, a, s| fake.run(t, a, s), &token, &plan(true, false));
+        let RuleOutcome::Failed(why) = &report.offer[0].1 else {
+            panic!("{report:?}");
+        };
+        assert!(why.contains("default route"), "{why}");
+        assert_eq!(fake.count("-f -"), 0);
+    }
+
+    #[test]
+    fn a_default_route_through_the_overlay_is_refused() {
+        let mut fake = Fake::new();
+        fake.default_route = Some("gateway: 10.13.37.1\ninterface: utun5\n".into());
+        let token = Mutex::new(None);
+        let report = apply_plan(&|t, a, s| fake.run(t, a, s), &token, &plan(true, false));
+        let RuleOutcome::Failed(why) = &report.offer[0].1 else {
+            panic!("{report:?}");
+        };
+        assert!(why.contains("already goes through"), "{why}");
+    }
+
+    #[test]
+    fn pf_is_enabled_once_and_released_once_on_clear() {
+        let fake = Fake::new();
+        let token = Mutex::new(None);
+        let run = |t, a: &[String], s: Option<&str>| fake.run(t, a, s);
+        apply_plan(&run, &token, &plan(true, false));
+        apply_plan(&run, &token, &plan(true, true));
+        assert_eq!(fake.count("Pfctl -E"), 1, "{:?}", fake.calls());
+
+        clear_all(&run, &token, "utun5");
+        assert_eq!(fake.count("Pfctl -X 4242"), 1);
+        assert!(
+            fake.position("-a com.apple/tsunagi-exit-utun5 -F all")
+                .is_some()
+        );
+        assert!(
+            fake.position("delete -net 0.0.0.0/1 -interface utun5")
+                .is_some()
+        );
+        assert_eq!(*token.lock().unwrap(), None);
+        // A second clear has nothing to release and still succeeds.
+        clear_all(&run, &token, "utun5");
+        assert_eq!(fake.count("Pfctl -X"), 1);
+    }
+
+    #[test]
+    fn dropping_the_client_removes_its_routes() {
+        let fake = Fake::new();
+        let token = Mutex::new(None);
+        let run = |t, a: &[String], s: Option<&str>| fake.run(t, a, s);
+        apply_plan(&run, &token, &plan(true, false));
+        assert!(fake.position("delete -net 0.0.0.0/1").is_some());
+        assert_eq!(fake.count(" add "), 0);
+    }
+}

crates/tsunagi-core/src/overlay/hostrules/mod.rs

@@ -45,19 +45,32 @@ use std::sync::{Arc, Mutex};
 use crate::BoxFuture;
 use crate::state::Ipv4Range;
 
+mod exit;
+pub use exit::{
+    ExitHostPlan, ExitHostReport, ExitHostRules, MockExitRules, exit_tag, exit_tag_prefix,
+    offer_detail,
+};
+
 #[cfg(all(feature = "tun-device", target_os = "linux"))]
 mod linux;
 #[cfg(all(feature = "tun-device", target_os = "linux"))]
+mod linux_exit;
+#[cfg(all(feature = "tun-device", target_os = "linux"))]
 pub use linux::LinuxHostRules;
 
 // Compiled everywhere so the scripts it builds are tested everywhere; only
 // the type that runs them is exported on Windows.
 mod windows;
+#[cfg_attr(not(target_os = "windows"), allow(dead_code))]
+mod windows_exit;
 #[cfg(all(feature = "tun-device", target_os = "windows"))]
 pub use windows::WindowsHostRules;
 
+// Compiled everywhere so its rule text and parsers are tested everywhere.
 #[cfg(all(feature = "tun-device", target_os = "macos"))]
 mod macos;
+#[cfg_attr(not(target_os = "macos"), allow(dead_code))]
+mod macos_exit;
 #[cfg(all(feature = "tun-device", target_os = "macos"))]
 pub use macos::MacosHostRules;
 
@@ -159,6 +172,15 @@ pub trait BroadcastHostRules: Send + Sync + std::fmt::Debug + 'static {
     /// Removes what this agent put there for the interface. Succeeds when
     /// nothing is there: it runs on the shutdown path.
     fn clear<'a>(&'a self, interface: &'a str) -> BoxFuture<'a, ()>;
+
+    /// The exit-node rules that go with these, when the platform has them.
+    ///
+    /// One object per host, because both halves need the same privileged
+    /// helpers; the default is that this platform has none, which is said
+    /// where it matters rather than pretended.
+    fn exit_rules(&self) -> Option<&dyn ExitHostRules> {
+        None
+    }
 }
 
 /// The platform has no implementation, which is said rather than pretended.
@@ -195,6 +217,7 @@ pub type MockRulesState = std::collections::BTreeMap<String, BroadcastRulesPlan>
 /// An in-memory host, for tests: nothing is touched.
 #[derive(Debug, Clone, Default)]
 pub struct MockHostRules {
+    exit: MockExitRules,
     state: Arc<Mutex<MockRulesState>>,
     calls: Arc<Mutex<Vec<String>>>,
     firewall_failure: Arc<Mutex<Option<String>>>,
@@ -203,7 +226,15 @@ pub struct MockHostRules {
 impl MockHostRules {
     /// An empty host.
     pub fn new() -> Self {
-        Self::default()
+        Self {
+            exit: MockExitRules::new(),
+            ..Self::default()
+        }
+    }
+
+    /// The exit-node half of this host, for inspecting and steering tests.
+    pub fn exit(&self) -> &MockExitRules {
+        &self.exit
     }
 
     /// Makes the firewall step fail with this reason from now on.
@@ -234,6 +265,10 @@ impl BroadcastHostRules for MockHostRules {
         "mock"
     }
 
+    fn exit_rules(&self) -> Option<&dyn ExitHostRules> {
+        Some(&self.exit)
+    }
+
     fn apply<'a>(&'a self, plan: &'a BroadcastRulesPlan) -> BoxFuture<'a, BroadcastRulesReport> {
         Box::pin(async move {
             lock(&self.calls).push(format!("apply:{}", plan.interface));

crates/tsunagi-core/src/overlay/hostrules/windows.rs

@@ -29,6 +29,8 @@
 
 use crate::BoxFuture;
 
+use super::exit::{ExitHostPlan, ExitHostReport, ExitHostRules};
+use super::windows_exit;
 use super::{BroadcastHostRules, BroadcastRulesPlan, BroadcastRulesReport, RuleOutcome, tag_for};
 
 /// A PowerShell single-quoted literal, with any embedded quote doubled.
@@ -90,7 +92,7 @@ fn classify(what: &str, text: &str) -> String {
         || lower.contains("run as administrator")
         || lower.contains("permissiondenied")
     {
-        format!("{what}: Windows refused; run tsunagi from an elevated (administrator) process")
+        format!("{what}: Windows refused; run tsng from an elevated (administrator) process")
     } else if lower.contains("is not recognized") || lower.contains("commandnotfound") {
         format!("{what}: the NetTCPIP/NetSecurity PowerShell modules are not available: {text}")
     } else if text.is_empty() {
@@ -113,6 +115,11 @@ fn powershell_path() -> std::path::PathBuf {
 
 /// Runs a script and returns what it said on failure.
 fn run_powershell(script: &str) -> Result<(), String> {
+    run_powershell_output(script).map(|_| ())
+}
+
+/// Runs a script and returns what it printed, or what it said on failure.
+fn run_powershell_output(script: &str) -> Result<String, String> {
     let output = std::process::Command::new(powershell_path())
         .args([
             "-NoProfile",
@@ -125,7 +132,7 @@ fn run_powershell(script: &str) -> Result<(), String> {
         .output()
         .map_err(|err| format!("could not run PowerShell: {err}"))?;
     if output.status.success() {
-        return Ok(());
+        return Ok(String::from_utf8_lossy(&output.stdout).into_owned());
     }
     let stderr = String::from_utf8_lossy(&output.stderr);
     let text = if stderr.trim().is_empty() {
@@ -155,11 +162,73 @@ impl WindowsHostRules {
     }
 }
 
+/// The IPv4 addresses a host name resolves to; empty when it does not.
+fn resolve_host(host: &str) -> Vec<std::net::Ipv4Addr> {
+    use std::net::{IpAddr, ToSocketAddrs};
+    (host, 443)
+        .to_socket_addrs()
+        .map(|addrs| {
+            addrs
+                .filter_map(|addr| match addr.ip() {
+                    IpAddr::V4(ip) => Some(ip),
+                    IpAddr::V6(_) => None,
+                })
+                .collect()
+        })
+        .unwrap_or_default()
+}
+
+impl ExitHostRules for WindowsHostRules {
+    fn needs_bypass(&self) -> bool {
+        true
+    }
+
+    fn apply<'a>(&'a self, plan: &'a ExitHostPlan) -> BoxFuture<'a, ExitHostReport> {
+        Box::pin(async move {
+            let job = plan.clone();
+            tokio::task::spawn_blocking(move || {
+                windows_exit::apply_plan(
+                    &|script| run_powershell_output(script),
+                    &resolve_host,
+                    &job,
+                )
+            })
+            .await
+            .unwrap_or_else(|err| {
+                let failed = RuleOutcome::Failed(format!("the task failed: {err}"));
+                ExitHostReport {
+                    offer: plan
+                        .offer
+                        .iter()
+                        .map(|range| (*range, failed.clone()))
+                        .collect(),
+                    forwarding: None,
+                    client: plan.client.then_some(failed),
+                }
+            })
+        })
+    }
+
+    fn clear<'a>(&'a self, interface: &'a str) -> BoxFuture<'a, ()> {
+        Box::pin(async move {
+            let name = interface.to_string();
+            let _ = tokio::task::spawn_blocking(move || {
+                windows_exit::clear_all(&|script| run_powershell_output(script), &name)
+            })
+            .await;
+        })
+    }
+}
+
 impl BroadcastHostRules for WindowsHostRules {
     fn name(&self) -> &str {
         "windows-netsecurity"
     }
 
+    fn exit_rules(&self) -> Option<&dyn ExitHostRules> {
+        Some(self)
+    }
+
     fn apply<'a>(&'a self, plan: &'a BroadcastRulesPlan) -> BoxFuture<'a, BroadcastRulesReport> {
         Box::pin(async move {
             let route = step("route", route_script(plan)).await;

crates/tsunagi-core/src/overlay/hostrules/windows_exit.rs

@@ -0,0 +1,603 @@
+//! Exit-node host rules on Windows: WinNAT through PowerShell.
+//!
+//! Compiled on every platform so the scripts and the plan logic are tested
+//! everywhere; only `WindowsHostRules` runs them, and only on Windows. It
+//! could not be run against a real Windows host while it was written.
+//!
+//! # Offering
+//!
+//! One NAT object per offered range, named with the usual tag
+//! `tsunagi-exit:<if>:<range>`:
+//!
+//! ```text
+//! New-NetNat -Name <tag> -InternalIPInterfaceAddressPrefix <range>
+//! ```
+//!
+//! WinNAT translates that range out of whichever interface the traffic leaves
+//! by, which is the Windows counterpart of the Linux masquerade. Windows
+//! forwards per interface, and the egress is not known here, so forwarding is
+//! only *read* for the overlay interface; turning it on for the interfaces
+//! involved is the owner's decision (`Set-NetIPInterface -Forwarding Enabled`).
+//! Some Windows versions allow a single NAT per host: a second offered range
+//! then reports its own failure.
+//!
+//! # Using
+//!
+//! Windows has no per-user or per-process routing, so the Linux scheme (an
+//! exemption for the agent's user) does not carry over. Instead the agent's
+//! own underlay traffic is exempted by *destination*:
+//!
+//! ```text
+//! New-NetRoute 0.0.0.0/1   on the overlay interface, metric 1
+//! New-NetRoute 128.0.0.0/1 on the overlay interface, metric 1
+//! New-NetRoute <ip>/32 via the physical default gateway, metric 7373
+//! ```
+//!
+//! The halves out-rank the default route without replacing it, so every more
+//! specific route (LAN, another VPN) keeps working. A `/32` per address the
+//! agent talks to directly (the verified direct paths of its connections, and
+//! the relays it uses, resolved when the rules are applied) keeps that traffic
+//! on the physical network instead of looping into the tunnel it carries. The
+//! metric 7373 marks those routes as ours, which is how stale ones are found
+//! and removed. Everything is written to the active store, so a reboot clears
+//! it. IPv6 is blackholed with `::/1` and `8000::/1` on the overlay interface,
+//! which has no IPv6: applications fall back to IPv4 after a delay, where
+//! Linux and macOS answer at once. The bypass follows the agent's paths as
+//! they change; a path that appears after the last apply is reached through
+//! the tunnel until the next one.
+//!
+//! The bypass routes are written before the halves, and removed after them.
+
+use super::RuleOutcome;
+use std::net::Ipv4Addr;
+
+use super::exit::{ExitHostPlan, ExitHostReport, exit_tag, exit_tag_prefix};
+use crate::state::Ipv4Range;
+
+/// The route metric that marks a bypass route as this agent's.
+const BYPASS_METRIC: u32 = 7373;
+
+/// Runs a PowerShell script and returns what it printed.
+pub(super) type RunScript<'a> = &'a dyn Fn(&str) -> Result<String, String>;
+
+/// Resolves a host name to its IPv4 addresses.
+pub(super) type Resolve<'a> = &'a dyn Fn(&str) -> Vec<Ipv4Addr>;
+
+/// A PowerShell single-quoted literal, with any embedded quote doubled.
+fn ps_literal(value: &str) -> String {
+    format!("'{}'", value.replace('\'', "''"))
+}
+
+/// Creates the NAT of one range, replacing one this agent made before.
+fn nat_script(interface: &str, range: &Ipv4Range) -> String {
+    let name = ps_literal(&exit_tag(interface, range));
+    let prefix = ps_literal(&range.to_string());
+    format!(
+        "$ErrorActionPreference = 'Stop'\n\
+         $name = {name}\n\
+         Get-NetNat -Name $name -ErrorAction SilentlyContinue | \
+         Remove-NetNat -Confirm:$false -ErrorAction SilentlyContinue\n\
+         New-NetNat -Name $name -InternalIPInterfaceAddressPrefix {prefix} | Out-Null\n"
+    )
+}
+
+/// Removes this interface's NAT objects except those named in `keep`.
+fn prune_script(interface: &str, keep: &[Ipv4Range]) -> String {
+    let prefix = ps_literal(&exit_tag_prefix(interface));
+    let keep: Vec<String> = keep
+        .iter()
+        .map(|range| ps_literal(&exit_tag(interface, range)))
+        .collect();
+    format!(
+        "$ErrorActionPreference = 'SilentlyContinue'\n\
+         $prefix = {prefix}\n\
+         $keep = @({})\n\
+         Get-NetNat | Where-Object {{ $_.Name.StartsWith($prefix) -and \
+         ($keep -notcontains $_.Name) }} | Remove-NetNat -Confirm:$false\n\
+         exit 0\n",
+        keep.join(", ")
+    )
+}
+
+/// Prints `Enabled` or `Disabled` for the interface's IPv4 forwarding.
+fn forwarding_script(interface: &str) -> String {
+    let alias = ps_literal(interface);
+    format!(
+        "$ErrorActionPreference = 'Stop'\n\
+         (Get-NetIPInterface -InterfaceAlias {alias} -AddressFamily IPv4).Forwarding\n"
+    )
+}
+
+/// Prints `<interface index> <next hop>` of the best default route that is
+/// not through the overlay interface.
+fn gateway_script(interface: &str) -> String {
+    let alias = ps_literal(interface);
+    format!(
+        "$ErrorActionPreference = 'Stop'\n\
+         $alias = {alias}\n\
+         $best = Get-NetRoute -DestinationPrefix '0.0.0.0/0' -AddressFamily IPv4 \
+         -PolicyStore ActiveStore | Where-Object {{ $_.InterfaceAlias -ne $alias -and \
+         $_.NextHop -ne '0.0.0.0' }} | Sort-Object {{ $_.RouteMetric + \
+         (Get-NetIPInterface -InterfaceIndex $_.InterfaceIndex -AddressFamily IPv4).InterfaceMetric }} | \
+         Select-Object -First 1\n\
+         if (-not $best) {{ throw 'the host has no default gateway outside the overlay' }}\n\
+         \"$($best.InterfaceIndex) $($best.NextHop)\"\n"
+    )
+}
+
+/// The default gateway as the script above printed it.
+fn parse_gateway(text: &str) -> Option<(u32, Ipv4Addr)> {
+    let mut words = text.split_whitespace();
+    let index = words.next()?.parse().ok()?;
+    let hop = words.next()?.parse().ok()?;
+    words.next().is_none().then_some((index, hop))
+}
+
+/// Replaces the bypass routes with one per address, through the gateway.
+fn bypass_script(index: u32, gateway: Ipv4Addr, addresses: &[Ipv4Addr]) -> String {
+    let list: Vec<String> = addresses
+        .iter()
+        .map(|address| ps_literal(&address.to_string()))
+        .collect();
+    format!(
+        "$ErrorActionPreference = 'Stop'\n\
+         Get-NetRoute -AddressFamily IPv4 -PolicyStore ActiveStore -ErrorAction SilentlyContinue | \
+         Where-Object {{ $_.RouteMetric -eq {BYPASS_METRIC} -and $_.DestinationPrefix.EndsWith('/32') }} | \
+         Remove-NetRoute -Confirm:$false -ErrorAction SilentlyContinue\n\
+         foreach ($ip in @({})) {{\n\
+         New-NetRoute -DestinationPrefix \"$ip/32\" -InterfaceIndex {index} -NextHop '{gateway}' \
+         -RouteMetric {BYPASS_METRIC} -PolicyStore ActiveStore -ErrorAction SilentlyContinue | Out-Null\n\
+         }}\n",
+        list.join(", ")
+    )
+}
+
+/// Sends everything else through the overlay interface.
+fn halves_script(interface: &str) -> String {
+    let alias = ps_literal(interface);
+    format!(
+        "$ErrorActionPreference = 'Stop'\n\
+         $alias = {alias}\n\
+         foreach ($p in '0.0.0.0/1', '128.0.0.0/1') {{\n\
+         Get-NetRoute -DestinationPrefix $p -InterfaceAlias $alias -PolicyStore ActiveStore \
+         -ErrorAction SilentlyContinue | Remove-NetRoute -Confirm:$false -ErrorAction SilentlyContinue\n\
+         New-NetRoute -DestinationPrefix $p -InterfaceAlias $alias -NextHop '0.0.0.0' \
+         -RouteMetric 1 -PolicyStore ActiveStore | Out-Null\n\
+         }}\n\
+         foreach ($p in '::/1', '8000::/1') {{\n\
+         Get-NetRoute -DestinationPrefix $p -InterfaceAlias $alias -PolicyStore ActiveStore \
+         -ErrorAction SilentlyContinue | Remove-NetRoute -Confirm:$false -ErrorAction SilentlyContinue\n\
+         New-NetRoute -DestinationPrefix $p -InterfaceAlias $alias -NextHop '::' \
+         -RouteMetric 1 -PolicyStore ActiveStore -ErrorAction SilentlyContinue | Out-Null\n\
+         }}\n"
+    )
+}
+
+/// Removes the halves and every bypass route. What is not there is the state
+/// wanted.
+fn remove_client_script(interface: &str) -> String {
+    let alias = ps_literal(interface);
+    format!(
+        "$ErrorActionPreference = 'SilentlyContinue'\n\
+         $alias = {alias}\n\
+         foreach ($p in '0.0.0.0/1', '128.0.0.0/1', '::/1', '8000::/1') {{\n\
+         Get-NetRoute -DestinationPrefix $p -InterfaceAlias $alias -PolicyStore ActiveStore | \
+         Remove-NetRoute -Confirm:$false\n\
+         }}\n\
+         Get-NetRoute -AddressFamily IPv4 -PolicyStore ActiveStore | \
+         Where-Object {{ $_.RouteMetric -eq {BYPASS_METRIC} -and $_.DestinationPrefix.EndsWith('/32') }} | \
+         Remove-NetRoute -Confirm:$false\n\
+         exit 0\n"
+    )
+}
+
+/// Every address to keep direct: the ones given and what the names resolve
+/// to, sorted and without duplicates.
+fn bypass_addresses(
+    resolve: Resolve<'_>,
+    addresses: &[Ipv4Addr],
+    hosts: &[String],
+) -> Vec<Ipv4Addr> {
+    let mut all: std::collections::BTreeSet<Ipv4Addr> = addresses.iter().copied().collect();
+    for host in hosts {
+        all.extend(resolve(host));
+    }
+    all.into_iter()
+        .filter(|a| !a.is_loopback() && !a.is_unspecified() && !a.is_multicast())
+        .collect()
+}
+
+fn apply_client(
+    run: RunScript<'_>,
+    resolve: Resolve<'_>,
+    plan: &ExitHostPlan,
+) -> Result<(), String> {
+    let interface = plan.interface.as_str();
+    let gateway = run(&gateway_script(interface))?;
+    let (index, hop) = parse_gateway(&gateway)
+        .ok_or_else(|| format!("cannot read the default gateway from `{}`", gateway.trim()))?;
+    let addresses = bypass_addresses(resolve, &plan.bypass, &plan.bypass_hosts);
+    run(&bypass_script(index, hop, &addresses))?;
+    if let Err(why) = run(&halves_script(interface)) {
+        // Do not leave a half-installed set: bypass routes alone are harmless
+        // but the next apply starts clean.
+        let _ = run(&remove_client_script(interface));
+        return Err(why);
+    }
+    Ok(())
+}
+
+fn parse_forwarding(text: &str) -> Option<bool> {
+    match text.trim().to_ascii_lowercase().as_str() {
+        "enabled" | "1" => Some(true),
+        "disabled" | "0" => Some(false),
+        _ => None,
+    }
+}
+
+/// Makes the host match the plan.
+pub(super) fn apply_plan(
+    run: RunScript<'_>,
+    resolve: Resolve<'_>,
+    plan: &ExitHostPlan,
+) -> ExitHostReport {
+    let interface = plan.interface.as_str();
+    // What an earlier plan left and this one no longer wants.
+    let pruned = run(&prune_script(interface, &plan.offer));
+    let offer = plan
+        .offer
+        .iter()
+        .map(|range| {
+            let outcome = match &pruned {
+                Err(why) => RuleOutcome::Failed(why.clone()),
+                Ok(_) => match run(&nat_script(interface, range)) {
+                    Ok(_) => RuleOutcome::Applied,
+                    Err(why) => RuleOutcome::Failed(why),
+                },
+            };
+            (*range, outcome)
+        })
+        .collect();
+    let client = if plan.client {
+        Some(match apply_client(run, resolve, plan) {
+            Ok(()) => RuleOutcome::Applied,
+            Err(why) => RuleOutcome::Failed(why),
+        })
+    } else {
+        // Whatever an earlier plan left must not stay in force.
+        let _ = run(&remove_client_script(interface));
+        None
+    };
+    let forwarding = if plan.offer.is_empty() {
+        None
+    } else {
+        run(&forwarding_script(interface))
+            .ok()
+            .and_then(|text| parse_forwarding(&text))
+    };
+    ExitHostReport {
+        offer,
+        forwarding,
+        client,
+    }
+}
+
+/// Removes every NAT object of this agent's for the interface.
+pub(super) fn clear_all(run: RunScript<'_>, interface: &str) {
+    if let Err(why) = run(&prune_script(interface, &[])) {
+        tracing::warn!(interface, "cannot remove the exit node NAT: {why}");
+    }
+    if let Err(why) = run(&remove_client_script(interface)) {
+        tracing::warn!(interface, "cannot remove the exit node routes: {why}");
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
+
+    use std::cell::RefCell;
+
+    use super::*;
+
+    fn range() -> Ipv4Range {
+        "10.13.37.0/24".parse().unwrap()
+    }
+
+    fn plan(client: bool) -> ExitHostPlan {
+        ExitHostPlan {
+            interface: "tsun0".into(),
+            offer: vec![range()],
+            client,
+            overlay: vec![range()],
+            ..Default::default()
+        }
+    }
+
+    #[test]
+    fn the_nat_is_named_with_the_tag_and_replaces_its_own() {
+        let script = nat_script("tsun0", &range());
+        assert!(
+            script.contains("$name = 'tsunagi-exit:tsun0:10.13.37.0/24'"),
+            "{script}"
+        );
+        assert!(script.contains("-InternalIPInterfaceAddressPrefix '10.13.37.0/24'"));
+        assert!(
+            script.find("Remove-NetNat").unwrap() < script.find("New-NetNat").unwrap(),
+            "{script}"
+        );
+    }
+
+    #[test]
+    fn a_quote_in_a_value_cannot_escape_the_literal() {
+        let script = nat_script("x'; Remove-Item C:\\ #", &range());
+        assert!(script.contains("'tsunagi-exit:x''; Remove-Item C:\\ #:10.13.37.0/24'"));
+        assert!(prune_script("x'y", &[]).contains("'tsunagi-exit:x''y:'"));
+        assert!(forwarding_script("x'y").contains("'x''y'"));
+    }
+
+    #[test]
+    fn pruning_keeps_wanted_ranges_and_only_selects_this_interfaces_nats() {
+        let script = prune_script("tsun0", &[range()]);
+        assert!(script.contains("$prefix = 'tsunagi-exit:tsun0:'"));
+        assert!(script.contains("$keep = @('tsunagi-exit:tsun0:10.13.37.0/24')"));
+        assert!(script.contains("StartsWith($prefix)"));
+        assert!(script.contains("exit 0"));
+        assert!(prune_script("tsun0", &[]).contains("$keep = @()"));
+    }
+
+    #[test]
+    fn forwarding_text_is_read_never_written() {
+        assert_eq!(parse_forwarding("Enabled\r\n"), Some(true));
+        assert_eq!(parse_forwarding("Disabled"), Some(false));
+        assert_eq!(parse_forwarding("what"), None);
+        let script = forwarding_script("tsun0");
+        assert!(script.contains("Get-NetIPInterface"));
+        assert!(!script.contains("Set-NetIPInterface"));
+    }
+
+    #[test]
+    fn offering_prunes_then_creates_and_reads_forwarding() {
+        let calls = RefCell::new(Vec::new());
+        let run = |script: &str| -> Result<String, String> {
+            calls.borrow_mut().push(script.to_string());
+            Ok(if script.contains("Get-NetIPInterface") {
+                "Disabled\n".to_string()
+            } else {
+                String::new()
+            })
+        };
+        let report = apply_plan(&run, &no_names, &plan(false));
+        assert_eq!(report.offer, vec![(range(), RuleOutcome::Applied)]);
+        assert_eq!(report.forwarding, Some(false));
+        assert_eq!(report.client, None);
+        let calls = calls.borrow();
+        assert!(calls[0].contains("StartsWith"), "{calls:?}");
+        assert!(calls[1].contains("New-NetNat"), "{calls:?}");
+        // Without a client, the routes of an earlier plan are taken away.
+        assert!(calls[2].contains("RouteMetric -eq 7373"), "{calls:?}");
+        assert!(calls[3].contains("Get-NetIPInterface"), "{calls:?}");
+    }
+
+    #[test]
+    fn a_failing_nat_is_that_ranges_failure() {
+        let run = |script: &str| -> Result<String, String> {
+            if script.contains("New-NetNat") {
+                Err("A NAT with this prefix already exists".into())
+            } else {
+                Ok(String::new())
+            }
+        };
+        let report = apply_plan(&run, &no_names, &plan(false));
+        let RuleOutcome::Failed(why) = &report.offer[0].1 else {
+            panic!("{report:?}");
+        };
+        assert!(why.contains("already exists"), "{why}");
+    }
+
+    fn no_names(_: &str) -> Vec<Ipv4Addr> {
+        Vec::new()
+    }
+
+    fn client_plan() -> ExitHostPlan {
+        ExitHostPlan {
+            interface: "tsun0".into(),
+            offer: Vec::new(),
+            client: true,
+            overlay: vec![range()],
+            bypass: vec![Ipv4Addr::new(138, 201, 61, 182)],
+            bypass_hosts: vec!["relay.example".into()],
+        }
+    }
+
+    #[test]
+    fn the_gateway_is_read_from_the_script_output() {
+        assert_eq!(
+            parse_gateway("12 192.168.1.1\r\n"),
+            Some((12, Ipv4Addr::new(192, 168, 1, 1)))
+        );
+        assert_eq!(parse_gateway(""), None);
+        assert_eq!(parse_gateway("12"), None);
+        assert_eq!(parse_gateway("12 gw"), None);
+        assert_eq!(parse_gateway("12 1.1.1.1 extra"), None);
+        let script = gateway_script("tsun0");
+        assert!(script.contains("-ne $alias"));
+        assert!(script.contains("-ne '0.0.0.0'"));
+    }
+
+    #[test]
+    fn bypass_routes_are_marked_host_routes_through_the_physical_gateway() {
+        let script = bypass_script(
+            12,
+            Ipv4Addr::new(192, 168, 1, 1),
+            &[Ipv4Addr::new(1, 2, 3, 4), Ipv4Addr::new(5, 6, 7, 8)],
+        );
+        assert!(script.contains("@('1.2.3.4', '5.6.7.8')"), "{script}");
+        assert!(script.contains("-InterfaceIndex 12 -NextHop '192.168.1.1'"));
+        assert!(script.contains("-RouteMetric 7373"));
+        assert!(script.contains("-PolicyStore ActiveStore"));
+        // Stale marked routes go first, and only /32 ones with our metric.
+        assert!(script.find("Remove-NetRoute").unwrap() < script.find("New-NetRoute").unwrap());
+        assert!(script.contains("RouteMetric -eq 7373"));
+        assert!(script.contains("EndsWith('/32')"));
+    }
+
+    #[test]
+    fn the_halves_go_through_the_overlay_and_ipv6_is_blackholed() {
+        let script = halves_script("tsun0");
+        assert!(script.contains("'0.0.0.0/1', '128.0.0.0/1'"));
+        assert!(script.contains("-InterfaceAlias $alias -NextHop '0.0.0.0'"));
+        assert!(script.contains("'::/1', '8000::/1'"));
+        assert!(script.contains("-PolicyStore ActiveStore"));
+        assert!(
+            !script.contains("0.0.0.0/0"),
+            "the default route is left alone"
+        );
+        assert!(halves_script("x'y").contains("'x''y'"));
+    }
+
+    #[test]
+    fn addresses_are_resolved_merged_and_cleaned() {
+        let resolve = |host: &str| -> Vec<Ipv4Addr> {
+            match host {
+                "relay.example" => vec![Ipv4Addr::new(9, 9, 9, 9), Ipv4Addr::new(1, 2, 3, 4)],
+                _ => Vec::new(),
+            }
+        };
+        let all = bypass_addresses(
+            &resolve,
+            &[
+                Ipv4Addr::new(1, 2, 3, 4),
+                Ipv4Addr::LOCALHOST,
+                Ipv4Addr::UNSPECIFIED,
+            ],
+            &["relay.example".into(), "gone.example".into()],
+        );
+        assert_eq!(
+            all,
+            vec![Ipv4Addr::new(1, 2, 3, 4), Ipv4Addr::new(9, 9, 9, 9)]
+        );
+    }
+
+    #[test]
+    fn the_bypass_is_written_before_the_halves_that_need_it() {
+        let calls = RefCell::new(Vec::new());
+        let run = |script: &str| -> Result<String, String> {
+            calls.borrow_mut().push(script.to_string());
+            Ok(if script.contains("Select-Object -First 1") {
+                "12 192.168.1.1\n".to_string()
+            } else {
+                String::new()
+            })
+        };
+        let resolve = |_: &str| vec![Ipv4Addr::new(9, 9, 9, 9)];
+        let report = apply_plan(&run, &resolve, &client_plan());
+        assert_eq!(report.client, Some(RuleOutcome::Applied));
+        let calls = calls.borrow();
+        let at = |needle: &str| calls.iter().position(|c| c.contains(needle)).unwrap();
+        assert!(at("Select-Object -First 1") < at("-RouteMetric 7373"));
+        assert!(at("-RouteMetric 7373") < at("'0.0.0.0/1', '128.0.0.0/1'"));
+        let bypass = &calls[at("-RouteMetric 7373")];
+        assert!(
+            bypass.contains("'9.9.9.9'") && bypass.contains("'138.201.61.182'"),
+            "{bypass}"
+        );
+    }
+
+    #[test]
+    fn nothing_goes_through_the_overlay_when_the_bypass_cannot_be_written() {
+        let run = |script: &str| -> Result<String, String> {
+            if script.contains("Select-Object -First 1") {
+                Ok("12 192.168.1.1".to_string())
+            } else if script.contains("-RouteMetric 7373") && script.contains("foreach ($ip") {
+                Err("Access is denied".to_string())
+            } else {
+                assert!(!script.contains("-NextHop '0.0.0.0'"), "{script}");
+                Ok(String::new())
+            }
+        };
+        let report = apply_plan(&run, &no_names, &client_plan());
+        assert_eq!(
+            report.client,
+            Some(RuleOutcome::Failed("Access is denied".into()))
+        );
+    }
+
+    #[test]
+    fn a_missing_gateway_is_a_failure_that_installs_no_route() {
+        let run = |script: &str| -> Result<String, String> {
+            assert!(!script.contains("New-NetRoute"), "{script}");
+            if script.contains("Select-Object -First 1") {
+                Err("the host has no default gateway outside the overlay".into())
+            } else {
+                Ok(String::new())
+            }
+        };
+        let report = apply_plan(&run, &no_names, &client_plan());
+        let Some(RuleOutcome::Failed(why)) = report.client else {
+            panic!("{report:?}");
+        };
+        assert!(why.contains("no default gateway"), "{why}");
+    }
+
+    #[test]
+    fn a_failed_halves_step_removes_what_was_written() {
+        let calls = RefCell::new(Vec::new());
+        let run = |script: &str| -> Result<String, String> {
+            calls.borrow_mut().push(script.to_string());
+            if script.contains("Select-Object -First 1") {
+                Ok("12 192.168.1.1".to_string())
+            } else if script.contains("'128.0.0.0/1'") && script.contains("New-NetRoute") {
+                Err("boom".to_string())
+            } else {
+                Ok(String::new())
+            }
+        };
+        let report = apply_plan(&run, &no_names, &client_plan());
+        assert!(matches!(report.client, Some(RuleOutcome::Failed(_))));
+        assert!(calls.borrow().last().unwrap().contains("Remove-NetRoute"));
+    }
+
+    #[test]
+    fn dropping_the_client_removes_its_routes_and_clearing_does_too() {
+        let calls = RefCell::new(Vec::new());
+        let run = |script: &str| -> Result<String, String> {
+            calls.borrow_mut().push(script.to_string());
+            Ok(String::new())
+        };
+        let report = apply_plan(&run, &no_names, &plan(false));
+        assert_eq!(report.client, None);
+        assert!(
+            calls
+                .borrow()
+                .iter()
+                .any(|c| c.contains("RouteMetric -eq 7373"))
+        );
+        let script = remove_client_script("tsun0");
+        assert!(script.contains("'0.0.0.0/1', '128.0.0.0/1', '::/1', '8000::/1'"));
+        assert!(script.contains("exit 0"));
+        // Only routes on our interface, or marked ours, are touched.
+        assert!(script.contains("-InterfaceAlias $alias"));
+        calls.borrow_mut().clear();
+        clear_all(&run, "tsun0");
+        assert!(
+            calls
+                .borrow()
+                .iter()
+                .any(|c| c.contains("RouteMetric -eq 7373"))
+        );
+    }
+
+    #[test]
+    fn clearing_prunes_everything_for_the_interface() {
+        let seen = RefCell::new(Vec::<String>::new());
+        let run = |script: &str| -> Result<String, String> {
+            seen.borrow_mut().push(script.to_string());
+            Ok(String::new())
+        };
+        clear_all(&run, "tsun0");
+        let seen = seen.borrow();
+        assert!(seen[0].contains("$keep = @()"));
+        assert!(seen[0].contains("'tsunagi-exit:tsun0:'"));
+    }
+}

crates/tsunagi-core/src/overlay/interface.rs

@@ -29,7 +29,11 @@ use tokio::task::JoinHandle;
 
 use crate::identity::NetworkId;
 
-use super::hostrules::{BroadcastHostRules, BroadcastRulesPlan, BroadcastRulesReport};
+use super::exit::{ExitRulesReport, RuleSetReport};
+use super::hostrules::{
+    BroadcastHostRules, BroadcastRulesPlan, BroadcastRulesReport, ExitHostPlan, ExitHostReport,
+    RuleOutcome, offer_detail,
+};
 use super::packet::IpHeader;
 use super::router::{Route, RoutingTable};
 use super::tun::{TunDevice, TunFactory, TunRequest};
@@ -158,6 +162,42 @@ pub struct Interface {
     host_rules: Option<Arc<dyn BroadcastHostRules>>,
     /// What those rules last reported, `None` while none are installed.
     rules_report: std::sync::Mutex<Option<BroadcastRulesReport>>,
+    /// What the exit-node rules were last asked for, and what came of it.
+    exit_state: std::sync::Mutex<ExitState>,
+    /// Where each network's runtime reaches its peers and relays outside the
+    /// overlay; read only by hosts that cannot exempt the agent from the
+    /// exit node's default route.
+    underlay: std::sync::Mutex<std::collections::HashMap<NetworkId, Underlay>>,
+}
+
+/// Underlay destinations one network's runtime currently depends on.
+#[derive(Debug, Default, Clone, PartialEq, Eq)]
+struct Underlay {
+    addresses: std::collections::BTreeSet<std::net::Ipv4Addr>,
+    hosts: std::collections::BTreeSet<String>,
+}
+
+/// The exit-node host rules as this interface last left them.
+#[derive(Debug, Default)]
+struct ExitState {
+    /// Whether what an earlier run left behind has been taken away. Done once,
+    /// at the first sync, whether or not anything is wanted now: a firewall
+    /// rule that forwards a range must not outlive the switch that offered it.
+    cleaned: bool,
+    /// What was last applied, `None` while nothing is.
+    plan: Option<ExitHostPlan>,
+    /// What came of it.
+    report: Option<ExitHostReport>,
+}
+
+impl ExitState {
+    /// Whether every step of the last apply took.
+    fn is_ok(&self) -> bool {
+        self.report.as_ref().is_some_and(|report| {
+            report.offer.iter().all(|(_, outcome)| outcome.is_applied())
+                && report.client.as_ref().is_none_or(RuleOutcome::is_applied)
+        })
+    }
 }
 
 impl Interface {
@@ -245,6 +285,8 @@ impl Interface {
             sync_lock: Arc::new(tokio::sync::Mutex::new(())),
             host_rules,
             rules_report: std::sync::Mutex::new(None),
+            exit_state: std::sync::Mutex::new(ExitState::default()),
+            underlay: std::sync::Mutex::new(std::collections::HashMap::new()),
         })
     }
 
@@ -298,6 +340,271 @@ impl Interface {
         }
     }
 
+    /// Brings the host's exit-node rules in line with the routing table.
+    ///
+    /// Idempotent, and cheap when nothing changed. It never fails: the
+    /// outcome is kept for [`Self::exit_rules`]. The first call also takes
+    /// away whatever an earlier run left, even when nothing is wanted now.
+    pub async fn sync_exit_rules(&self) {
+        let Some(exit) = self
+            .host_rules
+            .as_ref()
+            .and_then(|rules| rules.exit_rules())
+        else {
+            return;
+        };
+        let _guard = self.sync_lock.lock().await;
+        let mut ranges: Vec<_> = self
+            .routes
+            .exit_offers()
+            .into_iter()
+            .map(|(_, range)| range)
+            .collect();
+        ranges.sort_by_key(|range| (range.base, range.prefix_len));
+        ranges.dedup();
+        let client = self.routes.exit_via().is_some();
+        let overlay = self.routes.overlay_ranges();
+        let (bypass, bypass_hosts) = if client && exit.needs_bypass() {
+            self.underlay_targets(&overlay)
+        } else {
+            (Vec::new(), Vec::new())
+        };
+        let wanted = ExitHostPlan {
+            interface: self.name.clone(),
+            offer: ranges,
+            client,
+            overlay,
+            bypass,
+            bypass_hosts,
+        };
+
+        let first = !std::mem::replace(&mut self.exit_state().cleaned, true);
+        if first {
+            exit.clear(&self.name).await;
+        }
+        let (planned, ok) = {
+            let state = self.exit_state();
+            (state.plan.clone(), state.is_ok())
+        };
+        if wanted.is_empty() {
+            if planned.is_some() {
+                exit.clear(&self.name).await;
+                let mut state = self.exit_state();
+                state.plan = None;
+                state.report = None;
+                tracing::info!(interface = %self.name, "exit node host rules removed");
+            }
+            return;
+        }
+        if planned.as_ref() == Some(&wanted) && ok {
+            return;
+        }
+        let report = exit.apply(&wanted).await;
+        for (range, outcome) in &report.offer {
+            match outcome {
+                RuleOutcome::Applied => tracing::info!(
+                    interface = %self.name,
+                    %range,
+                    "exit node firewall rules applied"
+                ),
+                RuleOutcome::Failed(reason) => tracing::warn!(
+                    interface = %self.name,
+                    %range,
+                    "exit node firewall rules are incomplete: {reason}"
+                ),
+            }
+        }
+        if report.offer.iter().any(|(_, outcome)| outcome.is_applied())
+            && report.forwarding == Some(false)
+        {
+            tracing::warn!(
+                interface = %self.name,
+                "kernel forwarding is off for this interface, so nothing is forwarded for the \
+                 exit node yet: {}",
+                if cfg!(target_os = "windows") {
+                    "`Set-NetIPInterface -Forwarding Enabled` on the interfaces involved"
+                } else if cfg!(target_os = "macos") {
+                    "`sysctl -w net.inet.ip.forwarding=1`, set again after every reboot"
+                } else {
+                    "`sysctl -w net.ipv4.ip_forward=1` (or `net.ipv4.conf.<interface>.forwarding=1`), \
+                     and set it in sysctl.d to keep it"
+                }
+            );
+        }
+        match &report.client {
+            Some(RuleOutcome::Applied) => tracing::info!(
+                interface = %self.name,
+                "this device's traffic is routed through its exit node"
+            ),
+            Some(RuleOutcome::Failed(reason)) => tracing::warn!(
+                interface = %self.name,
+                "cannot route this device's traffic through the exit node: {reason}"
+            ),
+            None => {}
+        }
+        let mut state = self.exit_state();
+        state.plan = Some(wanted);
+        state.report = Some(report);
+    }
+
+    /// Tells the interface where a network's runtime reaches peers and
+    /// relays outside the overlay. When the host needs those kept out of the
+    /// exit node's default route and the set changed, the rules follow.
+    pub async fn set_underlay(
+        &self,
+        network: NetworkId,
+        addresses: impl IntoIterator<Item = std::net::Ipv4Addr>,
+        hosts: impl IntoIterator<Item = String>,
+    ) {
+        let new = Underlay {
+            addresses: addresses.into_iter().collect(),
+            hosts: hosts.into_iter().collect(),
+        };
+        let changed = {
+            let mut map = match self.underlay.lock() {
+                Ok(guard) => guard,
+                Err(poisoned) => poisoned.into_inner(),
+            };
+            if new == Underlay::default() {
+                map.remove(&network).is_some()
+            } else {
+                map.insert(network, new.clone()) != Some(new)
+            }
+        };
+        let needed = changed
+            && self.routes.exit_via().is_some()
+            && self
+                .host_rules
+                .as_ref()
+                .and_then(|rules| rules.exit_rules())
+                .is_some_and(|exit| exit.needs_bypass());
+        if needed {
+            self.sync_exit_rules().await;
+        }
+    }
+
+    /// Every underlay destination worth keeping direct, minus anything that
+    /// is the overlay itself, loopback or link-local.
+    fn underlay_targets(
+        &self,
+        overlay: &[crate::state::Ipv4Range],
+    ) -> (Vec<std::net::Ipv4Addr>, Vec<String>) {
+        let map = match self.underlay.lock() {
+            Ok(guard) => guard,
+            Err(poisoned) => poisoned.into_inner(),
+        };
+        let mut addresses = std::collections::BTreeSet::new();
+        let mut hosts = std::collections::BTreeSet::new();
+        for underlay in map.values() {
+            addresses.extend(underlay.addresses.iter().copied().filter(|address| {
+                !address.is_loopback()
+                    && !address.is_link_local()
+                    && !address.is_multicast()
+                    && !address.is_unspecified()
+                    && !address.is_broadcast()
+                    && !overlay.iter().any(|range| range.contains(*address))
+            }));
+            hosts.extend(underlay.hosts.iter().cloned());
+        }
+        (addresses.into_iter().collect(), hosts.into_iter().collect())
+    }
+
+    fn exit_state(&self) -> std::sync::MutexGuard<'_, ExitState> {
+        match self.exit_state.lock() {
+            Ok(guard) => guard,
+            Err(poisoned) => poisoned.into_inner(),
+        }
+    }
+
+    /// What the exit-node rules of a network are doing now.
+    ///
+    /// `offer` is `Some` while the network offers this agent as an exit node,
+    /// `client` while this device sends its traffic through a member of it.
+    pub fn exit_rules(&self, network: NetworkId) -> ExitRulesReport {
+        let Some((policy, range)) = self.routes.exit_settings(network) else {
+            return ExitRulesReport::default();
+        };
+        let unavailable = match self
+            .host_rules
+            .as_ref()
+            .map(|rules| rules.exit_rules().is_some())
+        {
+            None => Some(
+                "this overlay interface is not on the host (no TUN device), so there is \
+                 nothing to forward to",
+            ),
+            Some(false) => Some("exit nodes are not supported on this platform yet"),
+            Some(true) => None,
+        };
+        let failed = |detail: &str| RuleSetReport {
+            ok: false,
+            detail: detail.to_string(),
+        };
+        let state = self.exit_state();
+        let mut out = ExitRulesReport::default();
+        if policy.offer {
+            out.offer = Some(match (unavailable, range) {
+                (Some(why), _) => failed(why),
+                (None, None) => failed("waiting for the network to agree an address range"),
+                (None, Some(range)) => {
+                    match state
+                        .report
+                        .as_ref()
+                        .and_then(|report| report.offer.iter().find(|(r, _)| *r == range))
+                    {
+                        Some((_, outcome)) => RuleSetReport {
+                            ok: outcome.is_applied(),
+                            detail: offer_detail(outcome, &range),
+                        },
+                        None => failed("not applied yet"),
+                    }
+                }
+            });
+            if unavailable.is_none() {
+                out.forwarding = state.report.as_ref().and_then(|report| report.forwarding);
+            }
+        }
+        if policy.via.is_some()
+            && self
+                .routes
+                .exit_via()
+                .is_some_and(|(selected, _)| selected == network)
+        {
+            out.client = Some(match unavailable {
+                Some(why) => failed(why),
+                None => match state
+                    .report
+                    .as_ref()
+                    .and_then(|report| report.client.as_ref())
+                {
+                    Some(RuleOutcome::Applied) => RuleSetReport {
+                        ok: true,
+                        detail: "this device's traffic is routed through the exit node".to_string(),
+                    },
+                    Some(RuleOutcome::Failed(reason)) => failed(reason),
+                    None => failed("not applied yet"),
+                },
+            });
+        }
+        out
+    }
+
+    /// Whether this agent can really act as an exit node in a network: the
+    /// rules members' traffic needs are in place. Kernel forwarding is not
+    /// part of it, because the agent never turns that on itself.
+    pub fn exit_offer_ready(&self, network: NetworkId) -> bool {
+        let Some((policy, Some(range))) = self.routes.exit_settings(network) else {
+            return false;
+        };
+        policy.offer
+            && self.exit_state().report.as_ref().is_some_and(|report| {
+                report
+                    .offer
+                    .iter()
+                    .any(|(r, outcome)| *r == range && outcome.is_applied())
+            })
+    }
+
     /// What the broadcast host rules achieved, `None` when none are installed
     /// or this interface has no host to configure.
     pub fn broadcast_rules(&self) -> Option<BroadcastRulesReport> {
@@ -379,6 +686,16 @@ impl Interface {
         if let Some(rules) = &self.host_rules {
             rules.clear(&self.name).await;
             self.store_rules_report(None);
+            let touched = {
+                let state = self.exit_state();
+                state.cleaned || state.plan.is_some()
+            };
+            if let (true, Some(exit)) = (touched, rules.exit_rules()) {
+                exit.clear(&self.name).await;
+                let mut state = self.exit_state();
+                state.plan = None;
+                state.report = None;
+            }
         }
         // The packet loop holds the device open, and it ends only when the
         // device reports end of stream — which a real interface never does
@@ -435,6 +752,11 @@ impl Interface {
             IpAddr::V4(destination) if self.routes.is_local_destination(network, destination) => {
                 false
             }
+            // This agent is an exit node of this network: a member's packet
+            // for the internet goes to the host, which masquerades it.
+            IpAddr::V4(destination) if self.routes.accepts_exit_traffic(network, destination) => {
+                false
+            }
             _ => {
                 self.tally.wrong_destination.fetch_add(1, Ordering::Relaxed);
                 return Err(Rejected::WrongDestination);
@@ -525,7 +847,7 @@ mod tests {
     use crate::overlay::broadcast::BroadcastPolicy;
     use crate::overlay::hostrules::{MockHostRules, RuleOutcome};
     use crate::overlay::provision::{ManagedTunFactory, MockProvisioner};
-    use crate::overlay::router::NetworkRoutes;
+    use crate::overlay::router::{ExitPolicy, NetworkRoutes};
     use crate::overlay::tun::{MemoryTun, MemoryTunFactory};
 
     fn network(name: &str) -> NetworkId {
@@ -667,6 +989,7 @@ mod tests {
             .set_network(
                 id,
                 NetworkRoutes {
+                    exit: Default::default(),
                     broadcast: Default::default(),
                     range: Some("10.13.37.0/24".parse().unwrap()),
                     local: Some(addr(1)),
@@ -833,6 +1156,7 @@ mod tests {
             .set_network(
                 id,
                 NetworkRoutes {
+                    exit: Default::default(),
                     broadcast: Default::default(),
                     range: Some("10.13.37.0/24".parse().unwrap()),
                     local: Some(addr(9)),
@@ -856,6 +1180,7 @@ mod tests {
             .set_network(
                 id,
                 NetworkRoutes {
+                    exit: Default::default(),
                     broadcast: BroadcastPolicy {
                         enabled: broadcast_enabled,
                         ..Default::default()
@@ -910,6 +1235,7 @@ mod tests {
             .set_network(
                 id,
                 NetworkRoutes {
+                    exit: Default::default(),
                     broadcast: BroadcastPolicy::default(),
                     range: Some("10.13.37.0/24".parse().unwrap()),
                     local: Some(addr(9)),
@@ -978,4 +1304,320 @@ mod tests {
         assert!(interface.broadcast_rules().is_none());
         interface.remove().await;
     }
+
+    const INTERNET: Ipv4Addr = Ipv4Addr::new(93, 184, 216, 34);
+
+    fn offering() -> ExitPolicy {
+        ExitPolicy {
+            offer: true,
+            via: None,
+        }
+    }
+
+    fn using(exit: EndpointId) -> ExitPolicy {
+        ExitPolicy {
+            offer: false,
+            via: Some(exit),
+        }
+    }
+
+    #[tokio::test]
+    async fn internet_traffic_goes_to_the_exit_node_and_only_once_one_is_chosen() {
+        let (interface, device, routes, carrier, id) = interface(false).await;
+        device.push_from_os(ipv4(addr(1), INTERNET, b"before"));
+        wait_for(&interface, |counters| counters.unroutable).await;
+        assert!(carrier.carried().is_empty(), "no exit node, no route");
+
+        routes.set_exit(id, using(peer(2)));
+        device.push_from_os(ipv4(addr(1), INTERNET, b"after"));
+        wait_for(&interface, |counters| counters.sent).await;
+        let carried = carrier.carried();
+        assert_eq!(carried.len(), 1);
+        assert_eq!(carried[0].0.peer, peer(2));
+        assert_eq!(&carried[0].1[20..], b"after");
+    }
+
+    #[tokio::test]
+    async fn the_exit_node_may_answer_with_any_source_and_nobody_else_may() {
+        let (interface, device, routes, _carrier, id) = interface(false).await;
+        routes.set_exit(id, using(peer(2)));
+
+        interface
+            .deliver(id, peer(2), ipv4(INTERNET, addr(1), b"reply"))
+            .await
+            .unwrap();
+        let written = tokio::time::timeout(std::time::Duration::from_secs(5), device.pop_to_os())
+            .await
+            .expect("the reply reaches the interface")
+            .unwrap();
+        assert_eq!(&written[20..], b"reply");
+
+        // Another member cannot use the internet's addresses.
+        assert_eq!(
+            interface
+                .deliver(id, peer(3), ipv4(INTERNET, addr(1), b"spoof"))
+                .await,
+            Err(Rejected::WrongSource)
+        );
+        // Nor can the exit node speak for a member.
+        assert_eq!(
+            interface
+                .deliver(id, peer(2), ipv4(addr(3), addr(1), b"spoof"))
+                .await,
+            Err(Rejected::WrongSource)
+        );
+        // And what it sends still has to be for this agent.
+        assert_eq!(
+            interface
+                .deliver(id, peer(2), ipv4(INTERNET, addr(200), b"elsewhere"))
+                .await,
+            Err(Rejected::WrongDestination)
+        );
+        assert_eq!(interface.counters().received, 1);
+    }
+
+    #[tokio::test]
+    async fn an_exit_node_hands_a_members_internet_packet_to_the_host_only_while_offering() {
+        let (interface, device, routes, _carrier, id) = interface(false).await;
+
+        // Not offering: dropped exactly as before.
+        assert_eq!(
+            interface
+                .deliver(id, peer(2), ipv4(addr(2), INTERNET, b"request"))
+                .await,
+            Err(Rejected::WrongDestination)
+        );
+        assert_eq!(interface.counters().received, 0);
+
+        routes.set_exit(id, offering());
+        interface
+            .deliver(id, peer(2), ipv4(addr(2), INTERNET, b"request"))
+            .await
+            .unwrap();
+        let written = tokio::time::timeout(std::time::Duration::from_secs(5), device.pop_to_os())
+            .await
+            .expect("the request reaches the interface")
+            .unwrap();
+        assert_eq!(&written[20..], b"request");
+
+        // The source must still be the sender's own address.
+        assert_eq!(
+            interface
+                .deliver(id, peer(2), ipv4(addr(3), INTERNET, b"spoof"))
+                .await,
+            Err(Rejected::WrongSource)
+        );
+        assert_eq!(
+            interface
+                .deliver(id, peer(2), ipv4(INTERNET, INTERNET, b"spoof"))
+                .await,
+            Err(Rejected::WrongSource)
+        );
+        // Offering does not make this a door to the overlay or to this host.
+        for destination in [addr(3), addr(200), Ipv4Addr::LOCALHOST] {
+            assert_eq!(
+                interface
+                    .deliver(id, peer(2), ipv4(addr(2), destination, b"no"))
+                    .await,
+                Err(Rejected::WrongDestination),
+                "{destination}"
+            );
+        }
+        assert_eq!(interface.counters().received, 1);
+    }
+
+    #[tokio::test]
+    async fn the_underlay_reaches_the_rules_only_for_hosts_that_need_it_and_only_while_using_one() {
+        let rules = MockHostRules::new();
+        let (interface, routes, id) = managed_interface(&rules, false).await;
+        let relay = || vec!["relay.example".to_string()];
+        let direct = || {
+            vec![
+                Ipv4Addr::new(138, 201, 61, 182),
+                Ipv4Addr::new(10, 13, 37, 9), // the overlay itself
+                Ipv4Addr::LOCALHOST,
+                Ipv4Addr::new(169, 254, 1, 1),
+            ]
+        };
+
+        // A host that does not ask never gets them, so Linux and macOS do not
+        // re-apply their rules whenever a path moves.
+        routes.set_exit(id, using(peer(2)));
+        interface.set_underlay(id, direct(), relay()).await;
+        interface.sync_exit_rules().await;
+        let plan = rules.exit().installed().unwrap();
+        assert!(plan.client);
+        assert!(plan.bypass.is_empty() && plan.bypass_hosts.is_empty());
+
+        // A host that does gets the usable ones, and follows changes.
+        rules.exit().set_needs_bypass(true);
+        interface.set_underlay(id, direct(), relay()).await;
+        interface.sync_exit_rules().await;
+        let plan = rules.exit().installed().unwrap();
+        assert_eq!(plan.bypass, vec![Ipv4Addr::new(138, 201, 61, 182)]);
+        assert_eq!(plan.bypass_hosts, relay());
+        let applies = || {
+            rules
+                .exit()
+                .calls()
+                .iter()
+                .filter(|c| c.starts_with("apply"))
+                .count()
+        };
+        let before = applies();
+        interface.set_underlay(id, direct(), relay()).await;
+        assert_eq!(applies(), before, "an unchanged set is not applied again");
+        interface
+            .set_underlay(id, vec![Ipv4Addr::new(5, 6, 7, 8)], relay())
+            .await;
+        assert_eq!(applies(), before + 1);
+        assert_eq!(
+            rules.exit().installed().unwrap().bypass,
+            vec![Ipv4Addr::new(5, 6, 7, 8)]
+        );
+
+        // Not using an exit node: nothing to keep direct.
+        routes.set_exit(id, Default::default());
+        interface.sync_exit_rules().await;
+        interface
+            .set_underlay(id, vec![Ipv4Addr::new(1, 1, 1, 1)], relay())
+            .await;
+        assert!(rules.exit().installed().is_none());
+    }
+
+    #[tokio::test]
+    async fn the_exit_rules_follow_the_routing_table_and_leave_with_the_interface() {
+        let rules = MockHostRules::new();
+        let (interface, routes, id) = managed_interface(&rules, false).await;
+        let range: crate::state::Ipv4Range = "10.13.37.0/24".parse().unwrap();
+
+        // Nothing wanted: nothing installed, but what a crashed run left is
+        // taken away once.
+        interface.sync_exit_rules().await;
+        interface.sync_exit_rules().await;
+        assert_eq!(rules.exit().calls(), ["clear:tsunrules"]);
+        assert!(rules.exit().installed().is_none());
+        assert!(!interface.exit_offer_ready(id));
+        assert_eq!(interface.exit_rules(id), ExitRulesReport::default());
+
+        // Offering: the range is masqueraded, and the agent can say so.
+        routes.set_exit(id, offering());
+        assert!(!interface.exit_offer_ready(id), "not applied yet");
+        let waiting = interface.exit_rules(id).offer.unwrap();
+        assert!(!waiting.ok);
+        assert!(waiting.detail.contains("not applied yet"), "{waiting:?}");
+        interface.sync_exit_rules().await;
+        assert_eq!(rules.exit().installed().unwrap().offer, vec![range]);
+        assert!(interface.exit_offer_ready(id));
+        let report = interface.exit_rules(id);
+        assert!(report.offer.as_ref().unwrap().ok);
+        assert_eq!(report.forwarding, Some(true));
+        assert!(report.client.is_none());
+
+        // Unchanged: not applied again.
+        interface.sync_exit_rules().await;
+        assert_eq!(
+            rules
+                .exit()
+                .calls()
+                .iter()
+                .filter(|call| call.starts_with("apply"))
+                .count(),
+            1
+        );
+
+        // Forwarding off in the kernel: still installed, still ready, and said.
+        rules.exit().set_forwarding(Some(false));
+        routes.set_exit(
+            id,
+            ExitPolicy {
+                offer: true,
+                via: Some(peer(2)),
+            },
+        );
+        interface.sync_exit_rules().await;
+        assert!(rules.exit().installed().unwrap().client);
+        assert!(interface.exit_offer_ready(id));
+        let report = interface.exit_rules(id);
+        assert_eq!(report.forwarding, Some(false));
+        assert!(report.offer.unwrap().ok);
+        assert!(report.client.unwrap().ok);
+
+        // Turned off: removed, and no longer announced as ready.
+        routes.set_exit(id, ExitPolicy::default());
+        interface.sync_exit_rules().await;
+        assert!(rules.exit().installed().is_none());
+        assert!(!interface.exit_offer_ready(id));
+        assert_eq!(interface.exit_rules(id), ExitRulesReport::default());
+
+        routes.set_exit(id, offering());
+        interface.sync_exit_rules().await;
+        assert!(rules.exit().installed().is_some());
+        interface.remove().await;
+        assert!(
+            rules.exit().installed().is_none(),
+            "gone with the interface"
+        );
+    }
+
+    #[tokio::test]
+    async fn a_failed_exit_step_is_reported_and_the_agent_does_not_claim_to_be_an_exit_node() {
+        let rules = MockHostRules::new();
+        rules.exit().fail_with(Some("iptables needs root".into()));
+        let (interface, routes, id) = managed_interface(&rules, false).await;
+        routes.set_exit(id, offering());
+        interface.sync_exit_rules().await;
+
+        assert!(!interface.exit_offer_ready(id));
+        let offer = interface.exit_rules(id).offer.unwrap();
+        assert!(!offer.ok);
+        assert!(offer.detail.contains("iptables needs root"), "{offer:?}");
+
+        // It is tried again, not given up on, the next time it is asked.
+        rules.exit().fail_with(None);
+        interface.sync_exit_rules().await;
+        assert!(interface.exit_offer_ready(id));
+        interface.remove().await;
+    }
+
+    #[tokio::test]
+    async fn an_interface_without_a_host_cannot_be_an_exit_node_and_says_why() {
+        let (interface, _device, routes, _carrier, id) = interface(false).await;
+        routes.set_exit(
+            id,
+            ExitPolicy {
+                offer: true,
+                via: Some(peer(2)),
+            },
+        );
+        interface.sync_exit_rules().await;
+        assert!(!interface.exit_offer_ready(id));
+        let report = interface.exit_rules(id);
+        let offer = report.offer.unwrap();
+        assert!(!offer.ok);
+        assert!(offer.detail.contains("not on the host"), "{offer:?}");
+        assert!(!report.client.unwrap().ok);
+        interface.remove().await;
+    }
+
+    #[tokio::test]
+    async fn a_network_waiting_for_its_range_has_nothing_to_masquerade_yet() {
+        let rules = MockHostRules::new();
+        let (interface, routes, _id) = managed_interface(&rules, false).await;
+        let waiting = network("waiting");
+        routes
+            .set_network(
+                waiting,
+                NetworkRoutes {
+                    exit: offering(),
+                    ..Default::default()
+                },
+            )
+            .unwrap();
+        interface.sync_exit_rules().await;
+        assert!(rules.exit().installed().is_none());
+        let offer = interface.exit_rules(waiting).offer.unwrap();
+        assert!(offer.detail.contains("address range"), "{offer:?}");
+        interface.remove().await;
+    }
 }

crates/tsunagi-core/src/overlay/mod.rs

@@ -40,6 +40,7 @@ pub enum OverlayError {
 
 pub mod broadcast;
 pub mod config;
+pub mod exit;
 pub mod hostrules;
 pub mod interface;
 pub mod packet;
@@ -48,9 +49,10 @@ pub mod router;
 pub mod tun;
 
 pub use config::{Cidr, DEFAULT_INTERFACE_PREFIX, MAX_INTERFACE_NAME_LEN, interface_name};
+pub use exit::{ExitRulesReport, RuleSetReport};
 pub use hostrules::{
-    BroadcastHostRules, BroadcastRulesPlan, BroadcastRulesReport, MockHostRules, RuleOutcome,
+    BroadcastHostRules, BroadcastRulesPlan, BroadcastRulesReport, ExitHostPlan, ExitHostReport,
-    UnsupportedHostRules,
+    ExitHostRules, MockExitRules, MockHostRules, RuleOutcome, UnsupportedHostRules,
 };
 pub use interface::{Counters, Interface, PacketCarrier, Rejected};
 pub use packet::IpHeader;
@@ -59,7 +61,7 @@ pub use provision::{
     MockHost, MockProvisioner, Privilege, Provisioned, UnsupportedProvisioner, plan_changes,
     probe_net_admin,
 };
-pub use router::{NetworkRoutes, Route, RouteError, RoutingTable};
+pub use router::{ExitPolicy, NetworkRoutes, Route, RouteError, RoutingTable};
 pub use tun::{MemoryTun, MemoryTunFactory, TunDevice, TunFactory, TunRequest, address_is_local};
 
 #[cfg(all(feature = "tun-device", target_os = "linux"))]

crates/tsunagi-core/src/overlay/provision/linux.rs

@@ -48,7 +48,8 @@ use futures_util::TryStreamExt;
 use rtnetlink::packet_route::address::{AddressAttribute, AddressMessage};
 use rtnetlink::packet_route::link::{InfoKind, LinkAttribute, LinkFlags, LinkInfo, LinkMessage};
 use rtnetlink::packet_route::route::RouteScope;
-use rtnetlink::{LinkMessageBuilder, LinkUnspec, RouteMessageBuilder};
+use rtnetlink::packet_route::rule::{RuleAction, RuleAttribute, RuleMessage, RuleUidRange};
+use rtnetlink::{IpVersion, LinkMessageBuilder, LinkUnspec, RouteMessageBuilder};
 
 use crate::BoxFuture;
 use crate::overlay::OverlayError;
@@ -72,6 +73,11 @@ enum Command {
     SetBroadcastRoute(String, Ipv4Addr, Reply<()>),
     /// Remove that route from this interface.
     DelBroadcastRoute(String, Reply<()>),
+    /// Send the host's default traffic through this interface, except what
+    /// this user id sends.
+    SetExitClient(String, u32, Reply<()>),
+    /// Take those routing rules away again.
+    ClearExitClient(Reply<()>),
     /// Stop the thread.
     Stop,
 }
@@ -203,6 +209,20 @@ impl RouteHandle {
             Command::DelBroadcastRoute(interface, reply)
         })
     }
+
+    /// Sends the host's default traffic through `interface`, except what the
+    /// user id `uid` sends. Replaces what an earlier call set up.
+    pub(crate) fn set_exit_client(&self, interface: &str, uid: u32) -> Result<(), OverlayError> {
+        let interface = interface.to_string();
+        call_thread(&self.commands, |reply| {
+            Command::SetExitClient(interface, uid, reply)
+        })
+    }
+
+    /// Removes those rules. Succeeds when none are there.
+    pub(crate) fn clear_exit_client(&self) -> Result<(), OverlayError> {
+        call_thread(&self.commands, Command::ClearExitClient)
+    }
 }
 
 impl Drop for NetlinkProvisioner {
@@ -324,7 +344,11 @@ fn netlink_thread(requests: mpsc::Receiver<Command>) {
                     Command::Delete(_, reply)
                     | Command::Configure(_, reply)
                     | Command::SetBroadcastRoute(_, _, reply)
-                    | Command::DelBroadcastRoute(_, reply) => {
+                    | Command::DelBroadcastRoute(_, reply)
+                    | Command::SetExitClient(_, _, reply) => {
+                        let _ = reply.send(Err(OverlayError::Unavailable(message)));
+                    }
+                    Command::ClearExitClient(reply) => {
                         let _ = reply.send(Err(OverlayError::Unavailable(message)));
                     }
                     Command::Stop => return,
@@ -373,6 +397,22 @@ fn netlink_thread(requests: mpsc::Receiver<Command>) {
                 });
                 let _ = reply.send(result);
             }
+            Command::SetExitClient(name, uid, reply) => {
+                let result = NetAdmin::acquire().and_then(|guard| {
+                    let result = runtime.block_on(set_exit_client(&name, uid));
+                    drop(guard);
+                    result
+                });
+                let _ = reply.send(result);
+            }
+            Command::ClearExitClient(reply) => {
+                let result = NetAdmin::acquire().and_then(|guard| {
+                    let result = runtime.block_on(clear_exit_client());
+                    drop(guard);
+                    result
+                });
+                let _ = reply.send(result);
+            }
         }
     }
 }
@@ -596,6 +636,308 @@ async fn del_broadcast_route(name: &str) -> Result<(), OverlayError> {
     .await
 }
 
+/// The routing table that holds the exit node's default route: `tsun` in
+/// ASCII-ish hex, and nothing else uses it.
+const EXIT_TABLE: u32 = 0x7473;
+/// The main table.
+const MAIN_TABLE: u32 = 254;
+/// Where the exit rules sit, after Tailscale's 5270.
+const EXIT_BYPASS_PRIORITY: u32 = 5280;
+const EXIT_SPECIFIC_PRIORITY: u32 = 5290;
+const EXIT_DEFAULT_PRIORITY: u32 = 5300;
+
+/// The table a rule looks up.
+fn rule_table(rule: &RuleMessage) -> u32 {
+    rule.attributes
+        .iter()
+        .find_map(|attribute| match attribute {
+            RuleAttribute::Table(table) => Some(*table),
+            _ => None,
+        })
+        .unwrap_or(u32::from(rule.header.table))
+}
+
+fn rule_priority(rule: &RuleMessage) -> Option<u32> {
+    rule.attributes
+        .iter()
+        .find_map(|attribute| match attribute {
+            RuleAttribute::Priority(priority) => Some(*priority),
+            _ => None,
+        })
+}
+
+/// Whether a rule is one of the three this agent adds for an exit node.
+///
+/// Recognised by shape as well as priority: those numbers are not reserved,
+/// and a rule somebody else put at one of them must not be removed.
+fn is_exit_rule(rule: &RuleMessage) -> bool {
+    let table = rule_table(rule);
+    match rule_priority(rule) {
+        Some(EXIT_BYPASS_PRIORITY) => {
+            table == MAIN_TABLE
+                && rule
+                    .attributes
+                    .iter()
+                    .any(|attribute| matches!(attribute, RuleAttribute::UidRange(_)))
+        }
+        Some(EXIT_SPECIFIC_PRIORITY) => {
+            table == MAIN_TABLE
+                && rule
+                    .attributes
+                    .iter()
+                    .any(|attribute| matches!(attribute, RuleAttribute::SuppressPrefixLen(0)))
+        }
+        Some(EXIT_DEFAULT_PRIORITY) => table == EXIT_TABLE,
+        _ => false,
+    }
+}
+
+fn exit_default_route(index: Option<u32>) -> rtnetlink::packet_route::route::RouteMessage {
+    let mut builder = RouteMessageBuilder::<Ipv4Addr>::new()
+        .destination_prefix(Ipv4Addr::UNSPECIFIED, 0)
+        .table_id(EXIT_TABLE);
+    if let Some(index) = index {
+        builder = builder.output_interface(index).scope(RouteScope::Link);
+    }
+    builder.build()
+}
+
+/// The exit table's IPv6 default: nothing is reachable through it.
+///
+/// There is no IPv6 through an exit node, and what the ordinary route would do
+/// is send it out in the clear. This turns it into an immediate refusal, which
+/// is what makes applications fall back to IPv4.
+fn exit_blocking_route_v6() -> rtnetlink::packet_route::route::RouteMessage {
+    RouteMessageBuilder::<std::net::Ipv6Addr>::new()
+        .destination_prefix(std::net::Ipv6Addr::UNSPECIFIED, 0)
+        .table_id(EXIT_TABLE)
+        .kind(rtnetlink::packet_route::route::RouteType::Unreachable)
+        .build()
+}
+
+/// A host with no IPv6 at all has nothing to block, and says so this way.
+fn family_unsupported(err: &impl std::fmt::Display) -> bool {
+    let text = err.to_string();
+    text.contains("not supported") || text.contains("Address family")
+}
+
+/// Removes the exit node's routing rules and its tables. Nothing there is
+/// success: it also runs once at startup, for what a crashed run left.
+async fn clear_exit_client() -> Result<(), OverlayError> {
+    with_netlink(|handle| async move { remove_exit_client(&handle).await }).await
+}
+
+/// Deletes this agent's exit rules of one address family.
+async fn remove_exit_rules(
+    handle: &rtnetlink::Handle,
+    version: IpVersion,
+) -> Result<(), OverlayError> {
+    let mut rules = handle.rule().get(version).execute();
+    let mut ours = Vec::new();
+    while let Some(rule) = rules
+        .try_next()
+        .await
+        .map_err(|err| OverlayError::Unavailable(format!("cannot read the routing rules: {err}")))?
+    {
+        if is_exit_rule(&rule) {
+            ours.push(rule);
+        }
+    }
+    for rule in ours {
+        match handle.rule().del(rule).execute().await {
+            Ok(()) => {}
+            // Gone already.
+            Err(err) if err.to_string().contains("No such") => {}
+            Err(err) => {
+                return Err(OverlayError::Unavailable(format!(
+                    "cannot remove an exit node routing rule: {err}"
+                )));
+            }
+        }
+    }
+    Ok(())
+}
+
+async fn remove_exit_client(handle: &rtnetlink::Handle) -> Result<(), OverlayError> {
+    remove_exit_rules(handle, IpVersion::V4).await?;
+    match handle.route().del(exit_default_route(None)).execute().await {
+        Ok(()) => {}
+        // "No such process": no such route, which is the goal.
+        Err(err) if err.to_string().contains("No such") => {}
+        Err(err) => {
+            return Err(OverlayError::Unavailable(format!(
+                "cannot remove the exit node default route: {err}"
+            )));
+        }
+    }
+
+    match remove_exit_rules(handle, IpVersion::V6).await {
+        Ok(()) => {}
+        Err(OverlayError::Unavailable(reason)) if family_unsupported(&reason) => return Ok(()),
+        Err(err) => return Err(err),
+    }
+    match handle.route().del(exit_blocking_route_v6()).execute().await {
+        Ok(()) => Ok(()),
+        Err(err) if err.to_string().contains("No such") || family_unsupported(&err) => Ok(()),
+        Err(err) => Err(OverlayError::Unavailable(format!(
+            "cannot remove the exit node IPv6 block: {err}"
+        ))),
+    }
+}
+
+/// Sets up the using side of an exit node.
+///
+/// ```text
+/// ip route replace default dev <if> table 0x7473
+/// ip rule add priority 5280 uidrange <uid>-<uid> lookup main
+/// ip rule add priority 5290 lookup main suppress_prefixlength 0
+/// ip rule add priority 5300 lookup 0x7473
+/// ```
+///
+/// and the same for IPv6 with `ip -6 route replace unreachable default table
+/// 0x7473`, so that IPv6 is refused instead of leaving the ordinary way.
+///
+/// What an earlier call left is removed first, so repeating it is safe, and
+/// the rules go in last, so a failure part way never leaves a rule that
+/// sends traffic to a table with no route in it.
+async fn set_exit_client(name: &str, uid: u32) -> Result<(), OverlayError> {
+    with_netlink(|handle| async move {
+        let index = link_index(&handle, name).await.ok_or_else(|| {
+            OverlayError::Unavailable(format!(
+                "interface `{name}` disappeared before the exit node routes could be added"
+            ))
+        })?;
+        remove_exit_client(&handle).await?;
+        let fail = |what: &str, err: rtnetlink::Error| {
+            OverlayError::Unavailable(format!("cannot add the exit node {what}: {err}"))
+        };
+        handle
+            .route()
+            .add(exit_default_route(Some(index)))
+            .replace()
+            .execute()
+            .await
+            .map_err(|err| fail("default route", err))?;
+
+        let mut bypass = handle
+            .rule()
+            .add()
+            .v4()
+            .table_id(MAIN_TABLE)
+            .action(RuleAction::ToTable)
+            .priority(EXIT_BYPASS_PRIORITY);
+        bypass
+            .message_mut()
+            .attributes
+            .push(RuleAttribute::UidRange(RuleUidRange {
+                start: uid,
+                end: uid,
+            }));
+        bypass
+            .execute()
+            .await
+            .map_err(|err| fail("rule for the agent's own traffic", err))?;
+
+        let mut specific = handle
+            .rule()
+            .add()
+            .v4()
+            .table_id(MAIN_TABLE)
+            .action(RuleAction::ToTable)
+            .priority(EXIT_SPECIFIC_PRIORITY);
+        specific
+            .message_mut()
+            .attributes
+            .push(RuleAttribute::SuppressPrefixLen(0));
+        specific
+            .execute()
+            .await
+            .map_err(|err| fail("rule for the specific routes", err))?;
+
+        handle
+            .rule()
+            .add()
+            .v4()
+            .table_id(EXIT_TABLE)
+            .action(RuleAction::ToTable)
+            .priority(EXIT_DEFAULT_PRIORITY)
+            .execute()
+            .await
+            .map_err(|err| fail("rule for the default route", err))?;
+
+        set_exit_block_v6(&handle, uid).await
+    })
+    .await
+}
+
+/// The IPv6 half: an unreachable default for everything but the agent's own
+/// connections and the specific routes, which keep working.
+async fn set_exit_block_v6(handle: &rtnetlink::Handle, uid: u32) -> Result<(), OverlayError> {
+    let fail = |what: &str, err: rtnetlink::Error| {
+        OverlayError::Unavailable(format!("cannot add the exit node IPv6 {what}: {err}"))
+    };
+    if let Err(err) = handle
+        .route()
+        .add(exit_blocking_route_v6())
+        .replace()
+        .execute()
+        .await
+    {
+        // Without IPv6 there is nothing to leak.
+        return if family_unsupported(&err) {
+            Ok(())
+        } else {
+            Err(fail("block", err))
+        };
+    }
+
+    let mut bypass = handle
+        .rule()
+        .add()
+        .v6()
+        .table_id(MAIN_TABLE)
+        .action(RuleAction::ToTable)
+        .priority(EXIT_BYPASS_PRIORITY);
+    bypass
+        .message_mut()
+        .attributes
+        .push(RuleAttribute::UidRange(RuleUidRange {
+            start: uid,
+            end: uid,
+        }));
+    bypass
+        .execute()
+        .await
+        .map_err(|err| fail("rule for the agent's own traffic", err))?;
+
+    let mut specific = handle
+        .rule()
+        .add()
+        .v6()
+        .table_id(MAIN_TABLE)
+        .action(RuleAction::ToTable)
+        .priority(EXIT_SPECIFIC_PRIORITY);
+    specific
+        .message_mut()
+        .attributes
+        .push(RuleAttribute::SuppressPrefixLen(0));
+    specific
+        .execute()
+        .await
+        .map_err(|err| fail("rule for the specific routes", err))?;
+
+    handle
+        .rule()
+        .add()
+        .v6()
+        .table_id(EXIT_TABLE)
+        .action(RuleAction::ToTable)
+        .priority(EXIT_DEFAULT_PRIORITY)
+        .execute()
+        .await
+        .map_err(|err| fail("rule for the default route", err))
+}
+
 async fn configure_link(configure: &Configure) -> Result<(), OverlayError> {
     let name = configure.name.as_str();
     with_netlink(|handle| async move {
@@ -737,6 +1079,67 @@ mod tests {
         );
     }
 
+    fn rule(priority: u32, table: u32, extra: Vec<RuleAttribute>) -> RuleMessage {
+        let mut message = RuleMessage::default();
+        message.attributes.push(RuleAttribute::Priority(priority));
+        if table > 255 {
+            message.attributes.push(RuleAttribute::Table(table));
+        } else {
+            message.header.table = table as u8;
+        }
+        message.attributes.extend(extra);
+        message
+    }
+
+    #[test]
+    fn only_the_three_exit_rules_are_recognised_as_ours() {
+        let uid = RuleAttribute::UidRange(RuleUidRange { start: 5, end: 5 });
+        assert!(is_exit_rule(&rule(5280, 254, vec![uid.clone()])));
+        assert!(is_exit_rule(&rule(
+            5290,
+            254,
+            vec![RuleAttribute::SuppressPrefixLen(0)]
+        )));
+        assert!(is_exit_rule(&rule(5300, EXIT_TABLE, vec![])));
+
+        // Same priorities, somebody else's rules.
+        assert!(!is_exit_rule(&rule(5280, 254, vec![])));
+        assert!(!is_exit_rule(&rule(5290, 254, vec![])));
+        assert!(!is_exit_rule(&rule(5300, 52, vec![])));
+        assert!(!is_exit_rule(&rule(5270, 52, vec![])));
+        assert!(!is_exit_rule(&rule(5280, 100, vec![uid])));
+    }
+
+    #[test]
+    fn the_ipv6_default_of_the_exit_table_refuses_instead_of_routing() {
+        let route = exit_blocking_route_v6();
+        assert_eq!(route.header.destination_prefix_length, 0);
+        let debug = format!("{route:?}");
+        assert!(debug.contains("Unreachable"), "{debug}");
+        assert!(debug.contains(&format!("Table({EXIT_TABLE})")), "{debug}");
+        assert!(!debug.contains("Oif"), "{debug}");
+    }
+
+    #[test]
+    fn a_host_without_ipv6_is_not_a_failure() {
+        assert!(family_unsupported(
+            &"Address family not supported by protocol"
+        ));
+        assert!(family_unsupported(&"Operation not supported"));
+        assert!(!family_unsupported(&"Operation not permitted"));
+    }
+
+    #[test]
+    fn the_default_route_of_the_exit_table_names_the_table_and_the_interface() {
+        let route = exit_default_route(Some(7));
+        assert_eq!(route.header.destination_prefix_length, 0);
+        let debug = format!("{route:?}");
+        assert!(debug.contains(&format!("Table({EXIT_TABLE})")), "{debug}");
+        assert!(debug.contains("Oif(7)"), "{debug}");
+        // Deleting names no interface, so it matches whatever it was added on.
+        assert!(!format!("{:?}", exit_default_route(None)).contains("Oif"));
+    }
+
     #[test]
     fn an_interface_that_is_not_a_tun_is_reported_foreign() {
         let message = LinkMessage::default();

crates/tsunagi-core/src/overlay/provision/privilege.rs

@@ -15,7 +15,7 @@
 //! Grant it with:
 //!
 //! ```text
-//! sudo setcap cap_net_admin,cap_net_bind_service+p /usr/local/bin/tsunagi
+//! sudo setcap cap_net_admin,cap_net_bind_service+p /usr/local/bin/tsng
 //! ```
 //!
 //! `+p` rather than `+ep`: with `+p` the capability is permitted but not
@@ -171,7 +171,7 @@ mod linux_impl {
             caps::raise(None, CapSet::Effective, Capability::CAP_NET_ADMIN).map_err(|err| {
                 OverlayError::Unavailable(format!(
                     "cannot raise CAP_NET_ADMIN: {err}. {}",
-                    Privilege::how_to_grant("tsunagi")
+                    Privilege::how_to_grant("tsng")
                 ))
             })?;
             Ok(Self { raised: true })
@@ -204,10 +204,8 @@ mod tests {
 
     #[test]
     fn the_grant_instructions_name_the_program() {
-        let text = Privilege::how_to_grant("/usr/local/bin/tsunagi");
+        let text = Privilege::how_to_grant("/usr/local/bin/tsng");
-        assert!(
+        assert!(text.contains("setcap cap_net_admin,cap_net_bind_service+p /usr/local/bin/tsng"));
-            text.contains("setcap cap_net_admin,cap_net_bind_service+p /usr/local/bin/tsunagi")
-        );
         assert!(text.contains("--no-tun"), "the fallback is offered too");
     }
 

crates/tsunagi-core/src/overlay/router.rs

@@ -40,9 +40,21 @@ pub struct Route {
     pub peer: EndpointId,
 }
 
+/// A network's exit-node settings, as far as packets are concerned.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+pub struct ExitPolicy {
+    /// This agent offers itself as an exit node here: packets from members
+    /// for addresses outside every overlay range are handed to the host.
+    pub offer: bool,
+    /// The member all other traffic is sent to, if this device uses one.
+    pub via: Option<EndpointId>,
+}
+
 /// What one network contributes to the table.
 #[derive(Debug, Clone, Default, PartialEq, Eq)]
 pub struct NetworkRoutes {
+    /// Exit-node settings of this network.
+    pub exit: ExitPolicy,
     /// Local broadcast policy and authenticated willing recipients.
     pub broadcast: BroadcastPolicy,
     /// The range this network allocates from, once it has agreed one.
@@ -153,6 +165,16 @@ impl RoutingTable {
         }
     }
 
+    /// Replaces only a network's exit-node settings, without changing addresses.
+    ///
+    /// A network that has no entry yet (its range is not agreed) takes them
+    /// from [`NetworkRoutes::exit`] when it is added.
+    pub fn set_exit(&self, network: NetworkId, policy: ExitPolicy) {
+        if let Some(routes) = self.write().get_mut(&network) {
+            routes.exit = policy;
+        }
+    }
+
     /// Recognizes limited and configured subnet broadcasts before unicast lookup.
     pub fn is_broadcast(&self, destination: Ipv4Addr) -> bool {
         self.broadcast.load().is_destination(destination)
@@ -181,6 +203,10 @@ impl RoutingTable {
     ///
     /// This agent's own address returns `None`: a packet for ourselves does
     /// not go over a tunnel, and answering with a peer would send it to one.
+    ///
+    /// An address nobody holds, outside every overlay range and an ordinary
+    /// unicast destination, goes to this device's exit node when it has one:
+    /// that is what sending *all* traffic through a member means.
     pub fn route(&self, destination: Ipv4Addr) -> Option<Route> {
         let networks = self.read();
         for (network, routes) in networks.iter() {
@@ -198,17 +224,92 @@ impl RoutingTable {
                 });
             }
         }
-        None
+        // Inside an overlay range, an unowned address is nobody's, not the
+        // internet's.
+        if !is_internet_destination(destination) || in_any_range(&networks, destination) {
+            return None;
+        }
+        exit_via(&networks).map(|(network, peer)| Route { network, peer })
     }
 
     /// Whether a peer may send from a source address.
+    ///
+    /// A peer speaks only for the address the network agreed it holds. The
+    /// one exception is this device's exit node: what comes back from the
+    /// internet carries the internet's addresses, so from *that* peer any
+    /// source outside the overlay ranges is accepted.
     pub fn may_send_from(&self, network: NetworkId, peer: EndpointId, source: Ipv4Addr) -> bool {
-        self.read().get(&network).is_some_and(|routes| {
+        let networks = self.read();
-            routes
+        let Some(routes) = networks.get(&network) else {
-                .peers
+            return false;
-                .iter()
+        };
-                .any(|(address, holder)| *address == source && *holder == peer)
+        if routes
-        })
+            .peers
+            .iter()
+            .any(|(address, holder)| *address == source && *holder == peer)
+        {
+            return true;
+        }
+        routes.exit.via == Some(peer)
+            && is_internet_destination(source)
+            && !in_any_range(&networks, source)
+    }
+
+    /// Whether this agent, as an exit node of `network`, takes a member's
+    /// packet for `destination` to the host.
+    ///
+    /// Only an ordinary unicast address outside every overlay range, so a
+    /// packet for another member, for this agent or for the local network
+    /// segment never leaves by this door. The sender's own source address is
+    /// checked separately, by [`Self::may_send_from`].
+    pub fn accepts_exit_traffic(&self, network: NetworkId, destination: Ipv4Addr) -> bool {
+        let networks = self.read();
+        networks
+            .get(&network)
+            .is_some_and(|routes| routes.exit.offer)
+            && is_internet_destination(destination)
+            && !in_any_range(&networks, destination)
+    }
+
+    /// The network and member this device sends its internet traffic through.
+    ///
+    /// One default route, so one answer; if several networks claim one (they
+    /// should not) the lowest network id decides, so two runs agree.
+    pub fn exit_via(&self) -> Option<(NetworkId, EndpointId)> {
+        exit_via(&self.read())
+    }
+
+    /// Networks that offer this agent as an exit node, with the range each
+    /// agreed. A network that has not agreed one yet has nothing to
+    /// masquerade and is left out.
+    pub fn exit_offers(&self) -> Vec<(NetworkId, Ipv4Range)> {
+        let mut offers: Vec<(NetworkId, Ipv4Range)> = self
+            .read()
+            .iter()
+            .filter(|(_, routes)| routes.exit.offer)
+            .filter_map(|(network, routes)| Some((*network, routes.range?)))
+            .collect();
+        offers.sort_by_key(|(network, _)| *network);
+        offers
+    }
+
+    /// The range of every network in the table that has agreed one, sorted.
+    pub fn overlay_ranges(&self) -> Vec<Ipv4Range> {
+        let mut ranges: Vec<Ipv4Range> = self
+            .read()
+            .values()
+            .filter_map(|routes| routes.range)
+            .collect();
+        ranges.sort_by_key(|range| (range.base, range.prefix_len));
+        ranges.dedup();
+        ranges
+    }
+
+    /// One network's exit-node settings and its range, if it is in the table.
+    pub fn exit_settings(&self, network: NetworkId) -> Option<(ExitPolicy, Option<Ipv4Range>)> {
+        self.read()
+            .get(&network)
+            .map(|routes| (routes.exit, routes.range))
     }
 
     /// Whether an ordinary packet terminates on this host in this network.
@@ -275,6 +376,31 @@ impl RoutingTable {
     }
 }
 
+/// Whether an address is an ordinary unicast one: not this host, not a
+/// multicast or broadcast group, not link-local, not unspecified.
+fn is_internet_destination(address: Ipv4Addr) -> bool {
+    !(address.is_unspecified()
+        || address.is_loopback()
+        || address.is_multicast()
+        || address.is_broadcast()
+        || address.is_link_local())
+}
+
+/// Whether an address lies in any network's range.
+fn in_any_range(networks: &HashMap<NetworkId, NetworkRoutes>, address: Ipv4Addr) -> bool {
+    networks
+        .values()
+        .any(|routes| routes.range.is_some_and(|range| range.contains(address)))
+}
+
+/// The exit node in use, if any, from the lowest network that names one.
+fn exit_via(networks: &HashMap<NetworkId, NetworkRoutes>) -> Option<(NetworkId, EndpointId)> {
+    networks
+        .iter()
+        .filter_map(|(network, routes)| Some((*network, routes.exit.via?)))
+        .min_by_key(|(network, _)| *network)
+}
+
 /// Whether two ranges share any address.
 fn ranges_overlap(one: Ipv4Range, other: Ipv4Range) -> bool {
     // A range contains the other's base, or the other way round. With
@@ -308,6 +434,7 @@ mod tests {
 
     fn routes() -> NetworkRoutes {
         NetworkRoutes {
+            exit: Default::default(),
             broadcast: Default::default(),
             range: Some("10.13.37.0/24".parse().unwrap()),
             local: Some(addr(1)),
@@ -391,6 +518,7 @@ mod tests {
             .set_network(
                 second,
                 NetworkRoutes {
+                    exit: Default::default(),
                     broadcast: Default::default(),
                     range: Some("10.99.0.0/16".parse().unwrap()),
                     local: Some(Ipv4Addr::new(10, 99, 0, 1)),
@@ -420,6 +548,7 @@ mod tests {
             if a < b { (a, b) } else { (b, a) }
         };
         let mk = |enabled: bool, base: [u8; 4], local: Option<Ipv4Addr>| NetworkRoutes {
+            exit: Default::default(),
             broadcast: BroadcastPolicy {
                 enabled,
                 ..Default::default()
@@ -495,6 +624,7 @@ mod tests {
             .set_network(
                 network("wide"),
                 NetworkRoutes {
+                    exit: Default::default(),
                     broadcast: Default::default(),
                     range: Some("10.0.0.0/8".parse().unwrap()),
                     ..Default::default()
@@ -507,6 +637,7 @@ mod tests {
                 .set_network(
                     network("narrow"),
                     NetworkRoutes {
+                        exit: Default::default(),
                         broadcast: Default::default(),
                         range: Some("10.13.37.0/24".parse().unwrap()),
                         ..Default::default()
@@ -549,6 +680,7 @@ mod tests {
             .set_network(
                 network("two"),
                 NetworkRoutes {
+                    exit: Default::default(),
                     broadcast: Default::default(),
                     range: Some("10.99.0.0/16".parse().unwrap()),
                     local: Some(Ipv4Addr::new(10, 99, 0, 1)),
@@ -573,4 +705,233 @@ mod tests {
         assert_eq!(table.route(addr(2)), None);
         assert_eq!(table.len(), 1, "the network is known, it just has nothing");
     }
+
+    fn with_exit(offer: bool, via: Option<EndpointId>) -> NetworkRoutes {
+        NetworkRoutes {
+            exit: ExitPolicy { offer, via },
+            ..routes()
+        }
+    }
+
+    const INTERNET: Ipv4Addr = Ipv4Addr::new(93, 184, 216, 34);
+
+    #[test]
+    fn without_an_exit_node_the_internet_has_nowhere_to_go() {
+        let table = RoutingTable::new();
+        table.set_network(network("plain"), routes()).unwrap();
+        assert_eq!(table.route(INTERNET), None);
+        assert_eq!(table.exit_via(), None);
+    }
+
+    #[test]
+    fn with_an_exit_node_every_ordinary_destination_goes_to_it() {
+        let table = RoutingTable::new();
+        let id = network("client");
+        table
+            .set_network(id, with_exit(false, Some(peer(2))))
+            .unwrap();
+        let exit = Route {
+            network: id,
+            peer: peer(2),
+        };
+        assert_eq!(table.route(INTERNET), Some(exit));
+        assert_eq!(table.route(Ipv4Addr::new(192, 168, 1, 10)), Some(exit));
+        assert_eq!(table.exit_via(), Some((id, peer(2))));
+        // A member's own address still goes to that member.
+        assert_eq!(
+            table.route(addr(3)),
+            Some(Route {
+                network: id,
+                peer: peer(3)
+            })
+        );
+    }
+
+    #[test]
+    fn the_exit_node_is_never_the_answer_for_what_is_not_the_internet() {
+        let table = RoutingTable::new();
+        table
+            .set_network(network("client"), with_exit(false, Some(peer(2))))
+            .unwrap();
+        // Ourselves, a free address inside the overlay range, and everything
+        // that is not an ordinary unicast destination.
+        for destination in [
+            addr(1),
+            addr(200),
+            Ipv4Addr::new(127, 0, 0, 1),
+            Ipv4Addr::new(224, 0, 0, 251),
+            Ipv4Addr::new(239, 255, 255, 250),
+            Ipv4Addr::BROADCAST,
+            Ipv4Addr::UNSPECIFIED,
+            Ipv4Addr::new(169, 254, 1, 1),
+        ] {
+            assert_eq!(table.route(destination), None, "{destination}");
+        }
+    }
+
+    #[test]
+    fn another_networks_range_is_not_the_internet_either() {
+        let table = RoutingTable::new();
+        table
+            .set_network(network("client"), with_exit(false, Some(peer(2))))
+            .unwrap();
+        table
+            .set_network(
+                network("other"),
+                NetworkRoutes {
+                    range: Some("10.99.0.0/16".parse().unwrap()),
+                    local: Some(Ipv4Addr::new(10, 99, 0, 1)),
+                    ..Default::default()
+                },
+            )
+            .unwrap();
+        assert_eq!(table.route(Ipv4Addr::new(10, 99, 7, 7)), None);
+    }
+
+    #[test]
+    fn two_exit_choices_resolve_to_the_lowest_network_id() {
+        let table = RoutingTable::new();
+        let (a, b) = (network("one"), network("two"));
+        table
+            .set_network(a, with_exit(false, Some(peer(2))))
+            .unwrap();
+        table
+            .set_network(
+                b,
+                NetworkRoutes {
+                    exit: ExitPolicy {
+                        offer: false,
+                        via: Some(peer(9)),
+                    },
+                    range: Some("10.99.0.0/16".parse().unwrap()),
+                    ..Default::default()
+                },
+            )
+            .unwrap();
+        let (chosen, _) = table.exit_via().unwrap();
+        assert_eq!(chosen, a.min(b));
+        assert_eq!(table.route(INTERNET).unwrap().network, a.min(b));
+    }
+
+    #[test]
+    fn the_exit_peer_may_send_from_any_internet_address_but_nobody_else_may() {
+        let table = RoutingTable::new();
+        let id = network("client");
+        table
+            .set_network(id, with_exit(false, Some(peer(2))))
+            .unwrap();
+
+        // What comes back from the internet carries the internet's addresses.
+        assert!(table.may_send_from(id, peer(2), INTERNET));
+        // Another member still speaks only for its own address.
+        assert!(!table.may_send_from(id, peer(3), INTERNET));
+        assert!(table.may_send_from(id, peer(3), addr(3)));
+        // The exit peer cannot pass itself off as somebody else in the
+        // overlay, nor as this agent, nor as something that is not a source.
+        assert!(!table.may_send_from(id, peer(2), addr(3)));
+        assert!(!table.may_send_from(id, peer(2), addr(1)));
+        assert!(!table.may_send_from(id, peer(2), addr(200)));
+        for source in [
+            Ipv4Addr::LOCALHOST,
+            Ipv4Addr::UNSPECIFIED,
+            Ipv4Addr::new(224, 0, 0, 1),
+            Ipv4Addr::BROADCAST,
+        ] {
+            assert!(!table.may_send_from(id, peer(2), source), "{source}");
+        }
+        // Without choosing an exit node nobody gets the exception.
+        let plain = RoutingTable::new();
+        plain.set_network(id, routes()).unwrap();
+        assert!(!plain.may_send_from(id, peer(2), INTERNET));
+    }
+
+    #[test]
+    fn an_exit_node_takes_a_members_internet_packets_only_while_it_offers() {
+        let table = RoutingTable::new();
+        let id = network("server");
+        table.set_network(id, with_exit(false, None)).unwrap();
+        assert!(!table.accepts_exit_traffic(id, INTERNET));
+
+        table.set_exit(
+            id,
+            ExitPolicy {
+                offer: true,
+                via: None,
+            },
+        );
+        assert!(table.accepts_exit_traffic(id, INTERNET));
+        assert!(table.accepts_exit_traffic(id, Ipv4Addr::new(192, 168, 1, 10)));
+        // Never for another member, for this agent, a free overlay address,
+        // or anything that is not an ordinary unicast destination.
+        for destination in [
+            addr(1),
+            addr(2),
+            addr(200),
+            Ipv4Addr::LOCALHOST,
+            Ipv4Addr::new(224, 0, 0, 251),
+            Ipv4Addr::BROADCAST,
+            Ipv4Addr::UNSPECIFIED,
+        ] {
+            assert!(
+                !table.accepts_exit_traffic(id, destination),
+                "{destination}"
+            );
+        }
+        // An unknown network offers nothing.
+        assert!(!table.accepts_exit_traffic(network("elsewhere"), INTERNET));
+
+        table.set_exit(id, ExitPolicy::default());
+        assert!(!table.accepts_exit_traffic(id, INTERNET));
+    }
+
+    #[test]
+    fn offers_are_listed_by_network_with_the_range_each_agreed() {
+        let table = RoutingTable::new();
+        let (a, b) = (network("a"), network("b"));
+        table.set_network(a, with_exit(true, None)).unwrap();
+        table
+            .set_network(
+                b,
+                NetworkRoutes {
+                    exit: ExitPolicy {
+                        offer: true,
+                        via: None,
+                    },
+                    // No range agreed yet: nothing to masquerade.
+                    ..Default::default()
+                },
+            )
+            .unwrap();
+        assert_eq!(
+            table.exit_offers(),
+            vec![(a, "10.13.37.0/24".parse().unwrap())]
+        );
+        assert_eq!(
+            table.exit_settings(a),
+            Some((
+                ExitPolicy {
+                    offer: true,
+                    via: None
+                },
+                Some("10.13.37.0/24".parse().unwrap())
+            ))
+        );
+        assert_eq!(table.exit_settings(network("none")), None);
+    }
+
+    #[test]
+    fn setting_exit_for_a_network_with_no_entry_is_remembered_by_the_caller() {
+        // The runtime keeps the policy and passes it with the network when
+        // its range is agreed; a setter for a network the table does not know
+        // yet changes nothing.
+        let table = RoutingTable::new();
+        table.set_exit(
+            network("later"),
+            ExitPolicy {
+                offer: true,
+                via: None,
+            },
+        );
+        assert!(table.is_empty());
+    }
 }

crates/tsunagi-core/src/overlay/tun.rs

@@ -483,15 +483,15 @@ mod system {
         if denied {
             let hint = if cfg!(target_os = "windows") {
                 "Open PowerShell or Command Prompt with 'Run as administrator' and \
-                 start `tsunagi up` there."
+                 start `tsng up` there."
             } else if cfg!(target_os = "linux") {
-                "Start `tsunagi up` as root or grant CAP_NET_ADMIN with \
+                "Start `tsng up` as root or grant CAP_NET_ADMIN with \
                  `sudo setcap cap_net_admin,cap_net_bind_service+p /path/to/tsunagi`."
             } else if cfg!(target_os = "macos") {
-                "Creating a utun interface needs root on macOS; start `tsunagi up` \
+                "Creating a utun interface needs root on macOS; start `tsng up` \
                  with `sudo`, or install it as a root LaunchDaemon."
             } else {
-                "Start `tsunagi up` with the privileges required to create a TUN interface."
+                "Start `tsng up` with the privileges required to create a TUN interface."
             };
             return OverlayError::Unavailable(format!(
                 "permission denied while creating the TUN interface `{name}`. \
@@ -539,7 +539,7 @@ mod system {
             let message = open_error("tsun0", error).to_string();
             assert!(message.contains("permission denied"), "{message}");
             assert!(message.contains("tsun0"), "{message}");
-            assert!(message.contains("tsunagi up"), "{message}");
+            assert!(message.contains("tsng up"), "{message}");
             #[cfg(target_os = "windows")]
             assert!(message.contains("Run as administrator"), "{message}");
             #[cfg(target_os = "linux")]

crates/tsunagi-core/src/proto/message.rs

@@ -20,7 +20,7 @@ use crate::error::ProtocolError;
 /// The version in the ALPN is the wire-compatibility version of the control
 /// protocol. It is independent of the network identity scheme version, so
 /// bumping it must not change any existing [`crate::NetworkId`].
-pub const ALPN: &[u8] = b"tsunagi/ctrl/3";
+pub const ALPN: &[u8] = b"tsunagi/ctrl/5";
 
 /// ALPN of the tsunagi data plane.
 ///
@@ -30,9 +30,11 @@ pub const ALPN: &[u8] = b"tsunagi/ctrl/3";
 /// transport underneath can be replaced without touching the control protocol.
 ///
 /// Version 4 adds source, destination, hop limit and stable flow id above
-/// transport fragmentation. All members must upgrade together. Persistent
+/// transport fragmentation. Version 5 adds the end-to-end protocol to that
-/// identities and network configuration do not change.
+/// envelope, so a tunnel no longer depends on the kind of link under it, and
-pub const DATA_ALPN: &[u8] = b"tsunagi/data/4";
+/// a first-claimed time to a signed hostname claim. All members must upgrade
+/// together. Persistent identities and network configuration do not change.
+pub const DATA_ALPN: &[u8] = b"tsunagi/data/5";
 
 /// Largest plugin protocol identifier accepted when opening a data channel.
 pub const MAX_DATA_PROTOCOL_LEN: usize = 32;
@@ -41,7 +43,7 @@ pub const MAX_DATA_PROTOCOL_LEN: usize = 32;
 pub const MAX_SIGNATURE_LEN: usize = 64;
 
 /// Control protocol version carried inside the handshake.
-pub const PROTOCOL_VERSION: u16 = 3;
+pub const PROTOCOL_VERSION: u16 = 5;
 
 /// First message of the handshake, sent by the initiator.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
@@ -75,6 +77,11 @@ pub struct AuthProof {
 pub struct Announcement {
     /// Local opt-in to receive LAN broadcasts in this network.
     pub broadcast: bool,
+    /// This agent offers itself as an exit node in this network: members may
+    /// send all their internet traffic through it. Off unless its owner
+    /// turned it on, and only said once the rules that make it work are in
+    /// place.
+    pub exit_node: bool,
     /// Human-readable hostname. A mutable binding, not an identity.
     pub hostname: String,
     /// Announced IP plugin capabilities. Opaque to the core.

crates/tsunagi-core/src/state/mod.rs

@@ -150,7 +150,7 @@ pub fn derived_ipv4_range(network: NetworkId) -> Ipv4Range {
 }
 
 /// Frozen domain separator for the bytes a record signature covers.
-pub const RECORD_DOMAIN: &str = "tsunagi-signed-record-v2";
+pub const RECORD_DOMAIN: &str = "tsunagi-signed-record-v3";
 
 /// Longest hostname a record may carry.
 ///
@@ -207,6 +207,18 @@ pub enum RecordBody {
         range: Option<Ipv4Range>,
         /// The name this author answers to.
         hostname: Option<String>,
+        /// When this author first claimed that name, in milliseconds since
+        /// the Unix epoch, kept across every later version that keeps the
+        /// name. It is what makes a name belong to whoever claimed it first
+        /// rather than to whoever happens to sort lowest, so a member that
+        /// arrives later with the same name cannot take it over.
+        ///
+        /// The author's own word: a member with a wrong clock can claim an
+        /// earlier time. That costs it nothing it could not do by other
+        /// means, since anybody who knows the network secret is a member,
+        /// and it cannot take an address or reach anything it was not
+        /// already entitled to.
+        hostname_since: Option<u64>,
     },
     /// This author gives up everything it claimed.
     ///
@@ -243,6 +255,14 @@ impl RecordBody {
         }
     }
 
+    /// When the author first claimed the hostname, if it has one.
+    pub fn hostname_since(&self) -> Option<u64> {
+        match self {
+            RecordBody::Claim { hostname_since, .. } => *hostname_since,
+            RecordBody::Release => None,
+        }
+    }
+
     fn canonical(&self) -> Vec<u8> {
         let mut out = Vec::with_capacity(96);
         match self {
@@ -250,6 +270,7 @@ impl RecordBody {
                 address,
                 range,
                 hostname,
+                hostname_since,
             } => {
                 push_lp(&mut out, b"claim");
                 push_opt(
@@ -270,6 +291,13 @@ impl RecordBody {
                         .as_deref(),
                 );
                 push_opt(&mut out, hostname.as_deref().map(str::as_bytes));
+                push_opt(
+                    &mut out,
+                    hostname_since
+                        .map(|since| since.to_be_bytes())
+                        .as_ref()
+                        .map(|bytes| &bytes[..]),
+                );
             }
             RecordBody::Release => {
                 push_lp(&mut out, b"release");
@@ -391,8 +419,12 @@ impl SignedRecord {
             address,
             range,
             hostname,
+            hostname_since,
         } = &self.body
         {
+            if hostname.is_none() && hostname_since.is_some() {
+                return Err(StateError::Malformed("a time was claimed for no hostname"));
+            }
             // Bounds before anything is believed, because all of this came
             // off the network.
             if let Some(range) = range {
@@ -585,25 +617,33 @@ impl StateSet {
 
     /// Who currently holds each claimed hostname.
     ///
-    /// The same rule as addresses, for the same reason: a name is owned, two
+    /// A name belongs to the member that claimed it first, and the others
-    /// members may claim one, and every replica has to reach the same answer
+    /// that claim it keep working by address but are not found by that name.
-    /// about who has it without asking anybody.
+    /// "First" is the time each author signed into its own claim, with the
+    /// lower id deciding a tie and a claim with no time counting as last, so
+    /// every replica reaches the same answer about who has it without
+    /// asking anybody. It is a pure function of the records: nothing depends
+    /// on the order they arrived in, so there is no race to lose.
     pub fn hostname_holders(&self) -> HashMap<String, EndpointId> {
-        let mut holders: HashMap<String, EndpointId> = HashMap::new();
+        let mut holders: HashMap<String, (u64, EndpointId)> = HashMap::new();
         for (author, record) in &self.records {
             let Some(hostname) = record.body.hostname() else {
                 continue;
             };
+            let claim = (record.body.hostname_since().unwrap_or(u64::MAX), *author);
             holders
                 .entry(hostname.to_string())
                 .and_modify(|held| {
-                    if author.as_bytes() < held.as_bytes() {
+                    if (claim.0, claim.1.as_bytes()) < (held.0, held.1.as_bytes()) {
-                        *held = *author;
+                        *held = claim;
                     }
                 })
-                .or_insert(*author);
+                .or_insert(claim);
         }
         holders
+            .into_iter()
+            .map(|(hostname, (_, author))| (hostname, author))
+            .collect()
     }
 
     /// The hostname an author holds, if it holds one uncontested.
@@ -612,6 +652,19 @@ impl StateSet {
         (self.hostname_holders().get(hostname) == Some(author)).then_some(hostname)
     }
 
+    /// The name an author claimed and the member that holds it instead, when
+    /// somebody who claimed it earlier does.
+    pub fn hostname_taken(&self, author: &EndpointId) -> Option<(&str, EndpointId)> {
+        let hostname = self.records.get(author)?.body.hostname()?;
+        let holder = *self.hostname_holders().get(hostname)?;
+        (holder != *author).then_some((hostname, holder))
+    }
+
+    /// When an author first claimed the name it holds now, if it has one.
+    pub fn hostname_since_of(&self, author: &EndpointId) -> Option<u64> {
+        self.records.get(author)?.body.hostname_since()
+    }
+
     /// The address an author holds, if it holds one uncontested.
     pub fn address_of(&self, author: &EndpointId) -> Option<Ipv4Addr> {
         let address = self.records.get(author)?.body.claimed_address()?;
@@ -661,6 +714,7 @@ mod tests {
             address: Some(address.parse().unwrap()),
             range: Some(range()),
             hostname: None,
+            hostname_since: None,
         }
     }
 
@@ -720,6 +774,7 @@ mod tests {
                 address: Some("10.99.0.1".parse().unwrap()),
                 range: Some(range()),
                 hostname: None,
+                hostname_since: None,
             },
         );
         assert!(matches!(outside.verify(id), Err(StateError::Malformed(_))));
@@ -735,6 +790,7 @@ mod tests {
                     prefix_len: 31,
                 }),
                 hostname: None,
+                hostname_since: None,
             },
         );
         assert!(matches!(no_hosts.verify(id), Err(StateError::Malformed(_))));
@@ -776,6 +832,7 @@ mod tests {
                     address: None,
                     range: None,
                     hostname: Some(bad.to_string()),
+                    hostname_since: None,
                 },
             );
             assert!(
@@ -797,6 +854,7 @@ mod tests {
                 address: Some("10.13.37.5".parse().unwrap()),
                 range: None,
                 hostname: None,
+                hostname_since: None,
             },
         );
         assert!(matches!(record.verify(id), Err(StateError::Malformed(_))));
@@ -818,6 +876,7 @@ mod tests {
                     address: None,
                     range: None,
                     hostname: Some("music".into()),
+                    hostname_since: None,
                 },
             )
         };
@@ -860,6 +919,7 @@ mod tests {
                     address: None,
                     range: None,
                     hostname: Some(name.to_string()),
+                    hostname_since: None,
                 },
             )
         };
@@ -879,6 +939,109 @@ mod tests {
         assert_eq!(set.hostname_of(&secret.public()), Some("new"));
     }
 
+    fn named_at(
+        secret: &SecretKey,
+        id: NetworkId,
+        version: u64,
+        name: &str,
+        since: u64,
+    ) -> SignedRecord {
+        SignedRecord::sign(
+            secret,
+            id,
+            version,
+            RecordBody::Claim {
+                address: None,
+                range: None,
+                hostname: Some(name.into()),
+                hostname_since: Some(since),
+            },
+        )
+    }
+
+    #[test]
+    fn a_name_belongs_to_whoever_claimed_it_first_whatever_their_ids_or_arrival_order() {
+        let id = network("naming");
+        let mut keys = [SecretKey::generate(), SecretKey::generate()];
+        keys.sort_by_key(|key| *key.public().as_bytes());
+        let [low, high] = keys;
+
+        // The member with the higher id claimed first, so it holds the name,
+        // and the lower id does not take it back by sorting first.
+        let early = named_at(&high, id, 1, "music", 1_000);
+        let late = named_at(&low, id, 1, "music", 2_000);
+        for order in [[&early, &late], [&late, &early]] {
+            let mut set = StateSet::new();
+            for record in order {
+                set.merge(id, (*record).clone()).unwrap();
+            }
+            assert_eq!(set.hostname_of(&high.public()), Some("music"));
+            assert_eq!(set.hostname_of(&low.public()), None);
+            assert_eq!(
+                set.hostname_taken(&low.public()),
+                Some(("music", high.public()))
+            );
+            assert_eq!(set.hostname_taken(&high.public()), None);
+        }
+
+        // At the same instant the lower id decides, the same way everywhere.
+        let mut set = StateSet::new();
+        set.merge(id, named_at(&high, id, 1, "music", 5)).unwrap();
+        set.merge(id, named_at(&low, id, 1, "music", 5)).unwrap();
+        assert_eq!(set.hostname_of(&low.public()), Some("music"));
+        assert_eq!(set.hostname_of(&high.public()), None);
+    }
+
+    #[test]
+    fn a_name_that_loses_is_found_again_once_the_holder_lets_it_go() {
+        let id = network("naming");
+        let first = SecretKey::generate();
+        let second = SecretKey::generate();
+        let mut set = StateSet::new();
+        set.merge(id, named_at(&first, id, 1, "music", 1)).unwrap();
+        set.merge(id, named_at(&second, id, 1, "music", 2)).unwrap();
+        assert_eq!(set.hostname_of(&second.public()), None);
+
+        // Renaming starts the clock afresh, so it cannot be used to jump the
+        // queue for a name somebody else already holds.
+        set.merge(id, named_at(&first, id, 2, "other", 3)).unwrap();
+        assert_eq!(set.hostname_of(&second.public()), Some("music"));
+        set.merge(id, named_at(&first, id, 3, "music", 4)).unwrap();
+        assert_eq!(set.hostname_of(&second.public()), Some("music"));
+        assert_eq!(set.hostname_of(&first.public()), None);
+
+        // And a release hands it on.
+        set.merge(id, SignedRecord::sign(&second, id, 2, RecordBody::Release))
+            .unwrap();
+        assert_eq!(set.hostname_of(&first.public()), Some("music"));
+    }
+
+    #[test]
+    fn a_time_with_no_name_is_not_a_valid_claim() {
+        let id = network("naming");
+        let secret = SecretKey::generate();
+        let record = SignedRecord::sign(
+            &secret,
+            id,
+            1,
+            RecordBody::Claim {
+                address: None,
+                range: None,
+                hostname: None,
+                hostname_since: Some(1),
+            },
+        );
+        assert!(matches!(record.verify(id), Err(StateError::Malformed(_))));
+
+        // The time is signed: moving it breaks the signature, so nobody can
+        // improve another member's place in the queue.
+        let mut forged = named_at(&secret, id, 1, "music", 9_000);
+        if let RecordBody::Claim { hostname_since, .. } = &mut forged.body {
+            *hostname_since = Some(1);
+        }
+        assert_eq!(forged.verify(id).unwrap_err(), StateError::BadSignature);
+    }
+
     #[test]
     fn a_release_gives_up_the_name_as_well_as_the_address() {
         let secret = SecretKey::generate();
@@ -894,6 +1057,7 @@ mod tests {
                     address: Some("10.13.37.5".parse().unwrap()),
                     range: Some(range()),
                     hostname: Some("music".into()),
+                    hostname_since: None,
                 },
             ),
         )
@@ -1057,6 +1221,7 @@ mod tests {
                     address: Some("10.99.0.7".parse().unwrap()),
                     range: Some(custom),
                     hostname: None,
+                    hostname_since: None,
                 },
             ),
         )

crates/tsunagi-core/src/storage/mod.rs

@@ -254,6 +254,18 @@ impl Storage {
             .await
     }
 
+    /// Persists whether this agent offers itself as an exit node in a network.
+    pub async fn set_exit_node(&self, network_id: NetworkId, enabled: bool) -> Result<()> {
+        self.with_state(move |state| state.set_exit_node(network_id, enabled))
+            .await
+    }
+
+    /// Persists the member this device sends its internet traffic through.
+    pub async fn set_exit_via(&self, network_id: NetworkId, via: Option<[u8; 32]>) -> Result<()> {
+        self.with_state(move |state| state.set_exit_via(network_id, via.as_ref()))
+            .await
+    }
+
     /// Updates the auto-start flag of a network.
     pub async fn set_auto_start(&self, network_id: NetworkId, auto_start: bool) -> Result<()> {
         self.with_state(move |state| state.set_auto_start(network_id, auto_start))
@@ -264,7 +276,8 @@ impl Storage {
     pub async fn remove_network(&self, network_id: NetworkId) -> Result<()> {
         self.with_state(move |state| {
             state.remove_network(network_id)?;
-            state.forget_signed_records(network_id)
+            state.forget_signed_records(network_id)?;
+            state.forget_peer_hostnames(network_id)
         })
         .await?;
         self.with_cache((), move |cache| cache.forget_network(network_id))
@@ -283,6 +296,26 @@ impl Storage {
             .await
     }
 
+    /// Remembers the hostname a member announced, so it can still be named
+    /// once it is away.
+    pub async fn remember_peer_hostname(
+        &self,
+        network_id: NetworkId,
+        endpoint_id: [u8; 32],
+        hostname: String,
+    ) -> Result<()> {
+        self.with_state(move |state| {
+            state.remember_peer_hostname(network_id, &endpoint_id, &hostname)
+        })
+        .await
+    }
+
+    /// The hostnames members of a network last announced.
+    pub async fn peer_hostnames(&self, network_id: NetworkId) -> Result<Vec<([u8; 32], String)>> {
+        self.with_state(move |state| state.peer_hostnames(network_id))
+            .await
+    }
+
     /// Records an address hint. Failures are non-fatal.
     pub async fn record_hint(
         &self,

crates/tsunagi-core/src/storage/state.rs

@@ -21,7 +21,7 @@ use crate::identity::{DeviceIdentity, NetworkId, NetworkName, NetworkSecret};
 use crate::state::{RecordBody, SignedRecord};
 
 /// Schema version written by this build.
-pub const SCHEMA_VERSION: i64 = 4;
+pub const SCHEMA_VERSION: i64 = 7;
 
 /// Key of the stored hostname setting.
 const SETTING_HOSTNAME: &str = "hostname";
@@ -42,6 +42,10 @@ pub struct StoredNetwork {
     pub auto_start: bool,
     /// Local broadcast participation, enabled unless explicitly disabled.
     pub broadcast: bool,
+    /// This agent offers itself as an exit node here. Off unless turned on.
+    pub exit_node: bool,
+    /// The member this device sends all its internet traffic through, if any.
+    pub exit_via: Option<[u8; 32]>,
 }
 
 /// The mandatory state store.
@@ -191,13 +195,62 @@ impl StateStore {
                 PRAGMA user_version = 4;
                 COMMIT;").map_err(|err| self.corrupt(format!("cannot migrate schema to 4: {err}")))?;
         }
+        if found < 5 {
+            self.conn
+                .execute_batch(
+                    "BEGIN;
+                     CREATE TABLE IF NOT EXISTS peer_hostnames (
+                         network_id  BLOB NOT NULL,
+                         endpoint_id BLOB NOT NULL,
+                         hostname    TEXT NOT NULL,
+                         PRIMARY KEY (network_id, endpoint_id)
+                     );
+                     PRAGMA user_version = 5;
+                     COMMIT;",
+                )
+                .map_err(|err| self.corrupt(format!("cannot migrate schema to 5: {err}")))?;
+        }
+        if found < 6 {
+            self.conn
+                .execute_batch(
+                    "BEGIN;
+                     ALTER TABLE networks ADD COLUMN exit_node INTEGER NOT NULL DEFAULT 0 CHECK (exit_node IN (0,1));
+                     ALTER TABLE networks ADD COLUMN exit_via BLOB;
+                     PRAGMA user_version = 6;
+                     COMMIT;",
+                )
+                .map_err(|err| self.corrupt(format!("cannot migrate schema to 6: {err}")))?;
+        }
+        // Migration 6 -> 7: a claim gained the time its hostname was first
+        // claimed, which changed the signing domain. Records signed before
+        // no longer verify, so they are discarded rather than kept as rows
+        // every read has to reject; each member re-publishes its own claim on
+        // its next run and the others arrive again from their authors. The
+        // version counter is kept, so nothing is ever published twice at one
+        // version.
+        if found < 7 {
+            self.conn
+                .execute_batch(
+                    "BEGIN;
+                     DELETE FROM signed_records;
+                     PRAGMA user_version = 7;
+                     COMMIT;",
+                )
+                .map_err(|err| self.corrupt(format!("cannot migrate schema to 7: {err}")))?;
+        }
         Ok(())
     }
 
     /// Confirms the expected tables exist, so that a truncated or foreign
     /// database is reported rather than used.
     fn verify_shape(&self) -> Result<()> {
-        for table in ["device_identity", "networks", "settings", "signed_records"] {
+        for table in [
+            "device_identity",
+            "networks",
+            "settings",
+            "signed_records",
+            "peer_hostnames",
+        ] {
             let present: Option<String> = self
                 .conn
                 .query_row(
@@ -430,11 +483,56 @@ impl StateStore {
         Ok(())
     }
 
+    /// Saves whether this agent offers itself as an exit node in a network.
+    pub fn set_exit_node(&self, network_id: NetworkId, enabled: bool) -> Result<()> {
+        let changed = self
+            .conn
+            .execute(
+                "UPDATE networks SET exit_node = ?2 WHERE network_id = ?1",
+                params![network_id.as_bytes().as_slice(), enabled as i64],
+            )
+            .map_err(|err| Error::Storage(format!("cannot update exit node offer: {err}")))?;
+        if changed == 0 {
+            return Err(Error::NetworkUnknown(network_id));
+        }
+        Ok(())
+    }
+
+    /// Saves which member this device sends its internet traffic through.
+    ///
+    /// One device has one default route, so choosing an exit node in one
+    /// network clears the choice in every other.
+    pub fn set_exit_via(&self, network_id: NetworkId, via: Option<&[u8; 32]>) -> Result<()> {
+        let tx = self
+            .conn
+            .unchecked_transaction()
+            .map_err(|err| Error::Storage(format!("cannot update exit node: {err}")))?;
+        let changed = tx
+            .execute(
+                "UPDATE networks SET exit_via = ?2 WHERE network_id = ?1",
+                params![network_id.as_bytes().as_slice(), via.map(|v| v.as_slice())],
+            )
+            .map_err(|err| Error::Storage(format!("cannot update exit node: {err}")))?;
+        if changed == 0 {
+            return Err(Error::NetworkUnknown(network_id));
+        }
+        if via.is_some() {
+            tx.execute(
+                "UPDATE networks SET exit_via = NULL WHERE network_id != ?1",
+                params![network_id.as_bytes().as_slice()],
+            )
+            .map_err(|err| Error::Storage(format!("cannot update exit node: {err}")))?;
+        }
+        tx.commit()
+            .map_err(|err| Error::Storage(format!("cannot update exit node: {err}")))?;
+        Ok(())
+    }
+
     /// Lists every configured network.
     pub fn list_networks(&self) -> Result<Vec<StoredNetwork>> {
         let mut stmt = self
             .conn
-            .prepare("SELECT network_id, name, secret, auto_start, broadcast FROM networks ORDER BY name")
+            .prepare("SELECT network_id, name, secret, auto_start, broadcast, exit_node, exit_via FROM networks ORDER BY name")
             .map_err(|err| Error::Storage(format!("cannot list networks: {err}")))?;
         let rows = stmt
             .query_map([], |row| {
@@ -442,13 +540,21 @@ impl StateStore {
                 let name: String = row.get(1)?;
                 let secret: Vec<u8> = row.get(2)?;
                 let auto_start: i64 = row.get(3)?;
-                Ok((id, name, secret, auto_start != 0, row.get::<_, bool>(4)?))
+                Ok((
+                    id,
+                    name,
+                    secret,
+                    auto_start != 0,
+                    row.get::<_, bool>(4)?,
+                    row.get::<_, bool>(5)?,
+                    row.get::<_, Option<Vec<u8>>>(6)?,
+                ))
             })
             .map_err(|err| Error::Storage(format!("cannot list networks: {err}")))?;
 
         let mut out = Vec::new();
         for row in rows {
-            let (id, name, secret, auto_start, broadcast) =
+            let (id, name, secret, auto_start, broadcast, exit_node, exit_via) =
                 row.map_err(|err| Error::Storage(format!("cannot read network row: {err}")))?;
             let id: [u8; 32] = id
                 .as_slice()
@@ -460,6 +566,8 @@ impl StateStore {
                 secret: NetworkSecret::from_bytes(secret)?,
                 auto_start,
                 broadcast,
+                exit_node,
+                exit_via: exit_via.and_then(|bytes| <[u8; 32]>::try_from(bytes.as_slice()).ok()),
             });
         }
         Ok(out)
@@ -635,6 +743,61 @@ impl StateStore {
         Ok(())
     }
 
+    /// Remembers the hostname a member last announced.
+    pub fn remember_peer_hostname(
+        &self,
+        network_id: NetworkId,
+        endpoint_id: &[u8; 32],
+        hostname: &str,
+    ) -> Result<()> {
+        self.conn
+            .execute(
+                "INSERT INTO peer_hostnames (network_id, endpoint_id, hostname)
+                 VALUES (?1, ?2, ?3)
+                 ON CONFLICT(network_id, endpoint_id) DO UPDATE SET hostname = excluded.hostname",
+                params![
+                    network_id.as_bytes().as_slice(),
+                    endpoint_id.as_slice(),
+                    hostname
+                ],
+            )
+            .map_err(|err| Error::Storage(format!("cannot remember a hostname: {err}")))?;
+        Ok(())
+    }
+
+    /// The last hostname every member of a network announced.
+    pub fn peer_hostnames(&self, network_id: NetworkId) -> Result<Vec<([u8; 32], String)>> {
+        let mut stmt = self
+            .conn
+            .prepare("SELECT endpoint_id, hostname FROM peer_hostnames WHERE network_id = ?1")
+            .map_err(|err| Error::Storage(format!("cannot read hostnames: {err}")))?;
+        let rows = stmt
+            .query_map(params![network_id.as_bytes().as_slice()], |row| {
+                Ok((row.get::<_, Vec<u8>>(0)?, row.get::<_, String>(1)?))
+            })
+            .map_err(|err| Error::Storage(format!("cannot read hostnames: {err}")))?;
+        let mut out = Vec::new();
+        for row in rows {
+            let (id, hostname) =
+                row.map_err(|err| Error::Storage(format!("cannot read hostnames: {err}")))?;
+            if let Ok(id) = <[u8; 32]>::try_from(id.as_slice()) {
+                out.push((id, hostname));
+            }
+        }
+        Ok(out)
+    }
+
+    /// Forgets every remembered hostname of a network.
+    pub fn forget_peer_hostnames(&self, network_id: NetworkId) -> Result<()> {
+        self.conn
+            .execute(
+                "DELETE FROM peer_hostnames WHERE network_id = ?1",
+                params![network_id.as_bytes().as_slice()],
+            )
+            .map_err(|err| Error::Storage(format!("cannot forget hostnames: {err}")))?;
+        Ok(())
+    }
+
     /// Reads an arbitrary setting.
     pub fn get_setting(&self, key: &str) -> Result<Option<String>> {
         self.conn
@@ -698,6 +861,60 @@ mod broadcast_storage_tests {
     use super::*;
     use crate::identity::NetworkKeys;
 
+    #[test]
+    fn exit_node_choices_are_off_by_default_and_one_choice_clears_the_others() {
+        let dir = tempfile::tempdir().unwrap();
+        let store = StateStore::open(dir.path().join("state.sqlite")).unwrap();
+        let secret = NetworkSecret::from_bytes([5; 32]).unwrap();
+        let make = |name: &str| {
+            let name = NetworkName::new(name).unwrap();
+            let id = NetworkKeys::derive(&name, &secret).network_id();
+            store.upsert_network(id, &name, &secret, true).unwrap();
+            id
+        };
+        let (a, b) = (make("exit-a"), make("exit-b"));
+        let listed = || store.list_networks().unwrap();
+        assert!(
+            listed()
+                .iter()
+                .all(|n| !n.exit_node && n.exit_via.is_none())
+        );
+
+        store.set_exit_node(a, true).unwrap();
+        store.set_exit_via(a, Some(&[7; 32])).unwrap();
+        store.set_exit_via(b, Some(&[8; 32])).unwrap();
+        let by_id = |id: NetworkId| listed().into_iter().find(|n| n.network_id == id).unwrap();
+        assert!(by_id(a).exit_node, "offering is per network and kept");
+        assert_eq!(by_id(a).exit_via, None, "one default route: a was cleared");
+        assert_eq!(by_id(b).exit_via, Some([8; 32]));
+
+        store.set_exit_via(b, None).unwrap();
+        assert_eq!(by_id(b).exit_via, None);
+    }
+
+    #[test]
+    fn a_remembered_hostname_survives_a_restart_and_follows_the_latest_name() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("state.sqlite");
+        let name = NetworkName::new("hostnames").unwrap();
+        let secret = NetworkSecret::from_bytes([9; 32]).unwrap();
+        let id = NetworkKeys::derive(&name, &secret).network_id();
+        let peer = [3u8; 32];
+
+        let store = StateStore::open(&path).unwrap();
+        store.remember_peer_hostname(id, &peer, "laptop").unwrap();
+        store.remember_peer_hostname(id, &peer, "laptop-2").unwrap();
+        drop(store);
+
+        let store = StateStore::open(&path).unwrap();
+        assert_eq!(
+            store.peer_hostnames(id).unwrap(),
+            vec![(peer, "laptop-2".to_string())]
+        );
+        store.forget_peer_hostnames(id).unwrap();
+        assert!(store.peer_hostnames(id).unwrap().is_empty());
+    }
+
     #[test]
     fn v3_migration_preserves_identity_and_networks_and_defaults_broadcast_on() {
         let dir = tempfile::tempdir().unwrap();
@@ -714,7 +931,12 @@ mod broadcast_storage_tests {
         store.set_hostname("old-host").unwrap();
         store
             .conn
-            .execute_batch("ALTER TABLE networks DROP COLUMN broadcast; PRAGMA user_version=3;")
+            .execute_batch(
+                "ALTER TABLE networks DROP COLUMN broadcast; \
+             ALTER TABLE networks DROP COLUMN exit_node; \
+             ALTER TABLE networks DROP COLUMN exit_via; \
+             PRAGMA user_version=3;",
+            )
             .unwrap();
         drop(store);
         let store = StateStore::open(&path).unwrap();

crates/tsunagi-core/tests/identity.rs

@@ -0,0 +1,173 @@
+//! Scenario 1: deterministic network identity.
+//!
+//! The same name and secret must yield the same network space on different
+//! devices, and nothing else — hostname, device key, restart — may change it.
+
+#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
+
+use tsunagi::Agent;
+use tsunagi::discovery::SharedMemoryDiscovery;
+use tsunagi::identity::{NetworkKeys, NetworkName, NetworkSecret};
+use tsunagi::testing::{TestAgent, config_with, network};
+
+#[test]
+fn derivation_is_a_pure_function_of_name_and_secret() {
+    let name = NetworkName::new("home").unwrap();
+    let other = NetworkName::new("Home").unwrap();
+    let secret = NetworkSecret::generate();
+    let other_secret = NetworkSecret::generate();
+
+    let a = NetworkKeys::derive(&name, &secret);
+    let b = NetworkKeys::derive(&name, &secret);
+    assert_eq!(a.network_id(), b.network_id());
+    assert_eq!(a.discovery_key(), b.discovery_key());
+    assert_eq!(a.descriptor(), b.descriptor());
+
+    // A different name is a different space. Names are used verbatim, so case
+    // matters.
+    assert_ne!(
+        a.network_id(),
+        NetworkKeys::derive(&other, &secret).network_id()
+    );
+    // A different secret is a different space.
+    assert_ne!(
+        a.network_id(),
+        NetworkKeys::derive(&name, &other_secret).network_id()
+    );
+    // Separated key material: the discovery key is not the network id.
+    assert_ne!(a.network_id().as_bytes(), a.discovery_key().as_bytes());
+}
+
+#[test]
+fn descriptor_carries_no_creator_time_or_secret() {
+    let name = NetworkName::new("shared").unwrap();
+    let secret = NetworkSecret::generate();
+    let first = NetworkKeys::derive(&name, &secret).descriptor();
+    let second = NetworkKeys::derive(&name, &secret).descriptor();
+
+    // Two independently built descriptors are byte identical: no random
+    // creator id, no creation timestamp, no owner signature.
+    assert_eq!(first.to_canonical_bytes(), second.to_canonical_bytes());
+
+    let encoded = first.to_canonical_bytes();
+    let secret_bytes = secret.encode();
+    assert!(
+        !encoded
+            .windows(secret_bytes.len())
+            .any(|window| window == secret_bytes.as_bytes()),
+        "the secret must never appear in the public descriptor"
+    );
+}
+
+#[test]
+fn names_are_validated_not_silently_normalised() {
+    assert!(NetworkName::new("").is_err());
+    assert!(NetworkName::new(" home").is_err(), "must not be trimmed");
+    assert!(NetworkName::new("home ").is_err(), "must not be trimmed");
+    assert!(NetworkName::new("ho\nme").is_err());
+    assert!(NetworkName::new("a".repeat(65)).is_err());
+    assert_eq!(NetworkName::new("home").unwrap().as_str(), "home");
+}
+
+#[test]
+fn secrets_are_not_truncated_or_normalised() {
+    let secret = NetworkSecret::generate();
+    let text = secret.encode();
+    let round_tripped = NetworkSecret::decode(&text).unwrap();
+    assert_eq!(secret, round_tripped);
+
+    // Short secrets are rejected rather than stretched.
+    assert!(NetworkSecret::from_bytes(vec![7u8; 15]).is_err());
+    assert!(NetworkSecret::from_bytes(vec![7u8; 16]).is_ok());
+
+    // Debug output must not leak the secret.
+    let rendered = format!("{secret:?}");
+    assert_eq!(rendered, "NetworkSecret(<redacted>)");
+}
+
+#[tokio::test]
+async fn different_devices_and_hostnames_agree_on_the_network_id() {
+    let discovery = SharedMemoryDiscovery::new();
+    let (name, secret) = network("agreement");
+
+    let a = TestAgent::spawn_with(|cfg| cfg.with_hostname("alpha"), &discovery)
+        .await
+        .unwrap();
+    let b = TestAgent::spawn_with(|cfg| cfg.with_hostname("beta"), &discovery)
+        .await
+        .unwrap();
+
+    assert_ne!(
+        a.agent.endpoint_id(),
+        b.agent.endpoint_id(),
+        "different devices must have different endpoint ids"
+    );
+    assert_eq!(a.agent.hostname(), "alpha");
+    assert_eq!(b.agent.hostname(), "beta");
+
+    let id_a = a.agent.join_network(&name, &secret).await.unwrap();
+    let id_b = b.agent.join_network(&name, &secret).await.unwrap();
+    assert_eq!(id_a, id_b);
+
+    a.agent.shutdown().await;
+    b.agent.shutdown().await;
+}
+
+#[tokio::test]
+async fn restart_keeps_the_device_and_network_identity() {
+    let discovery = SharedMemoryDiscovery::new();
+    let (name, secret) = network("stable");
+
+    let first = TestAgent::spawn(&discovery).await.unwrap();
+    let device_id = first.agent.endpoint_id();
+    let network_id = first.agent.join_network(&name, &secret).await.unwrap();
+    let dir = first.stop().await;
+
+    let reopened = Agent::spawn(config_with(dir.path(), &discovery))
+        .await
+        .unwrap();
+    assert_eq!(
+        reopened.endpoint_id(),
+        device_id,
+        "restarting must not mint a new peer"
+    );
+    let networks = reopened.list_networks().await.unwrap();
+    assert_eq!(networks.len(), 1);
+    assert_eq!(networks[0].network_id, network_id);
+    assert!(networks[0].active, "auto-start networks come back up");
+
+    reopened.shutdown().await;
+    drop(reopened);
+    drop(dir);
+}
+
+#[tokio::test]
+async fn changing_the_secret_keeps_the_device_identity() {
+    let discovery = SharedMemoryDiscovery::new();
+    let dir = tempfile::TempDir::new().unwrap();
+    let agent = Agent::spawn(config_with(dir.path(), &discovery))
+        .await
+        .unwrap();
+    let device_id = agent.endpoint_id();
+
+    let name = NetworkName::new("rotating").unwrap();
+    let old = agent
+        .join_network(&name, &NetworkSecret::generate())
+        .await
+        .unwrap();
+    let new = agent
+        .join_network(&name, &NetworkSecret::generate())
+        .await
+        .unwrap();
+
+    assert_ne!(old, new, "a new secret is a new network space");
+    assert_eq!(
+        agent.endpoint_id(),
+        device_id,
+        "rotating the network secret must not change the persistent iroh id"
+    );
+
+    agent.shutdown().await;
+    drop(agent);
+    drop(dir);
+}

crates/tsunagi-core/tests/mixed_transports.rs

@@ -0,0 +1,308 @@
+//! Connectivity does not depend on what kind of link each hop happens to be,
+//! and a member is online however far away it is.
+
+#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
+
+use std::collections::{HashMap, HashSet};
+use std::sync::{Arc, Mutex};
+
+use bytes::Bytes;
+use iroh::EndpointId;
+use tsunagi::NetworkId;
+use tsunagi::agent::DataPath;
+use tsunagi::dataplane::transport::SharedLink;
+use tsunagi::dataplane::{IpPlugin, PluginCapability, PluginError};
+use tsunagi::discovery::SharedMemoryDiscovery;
+use tsunagi::testing::{TestAgent, network, wait_for_peers, wait_until};
+
+/// A protocol that moves bytes between two members unchanged and keeps the
+/// link it was handed, so a test can use the link directly.
+#[derive(Debug)]
+struct Carrier {
+    protocol: String,
+    links: Mutex<HashMap<EndpointId, SharedLink>>,
+}
+
+impl Carrier {
+    fn new(protocol: &str) -> Arc<Self> {
+        Arc::new(Self {
+            protocol: protocol.into(),
+            links: Mutex::default(),
+        })
+    }
+
+    fn link(&self, peer: EndpointId) -> Option<SharedLink> {
+        self.links.lock().unwrap().get(&peer).cloned()
+    }
+}
+
+impl IpPlugin for Carrier {
+    fn protocol_id(&self) -> &str {
+        &self.protocol
+    }
+
+    fn protocol_version(&self) -> u16 {
+        1
+    }
+
+    fn local_capability(
+        &self,
+        _network: NetworkId,
+    ) -> Result<Option<PluginCapability>, PluginError> {
+        Ok(Some(PluginCapability {
+            protocol: self.protocol.clone(),
+            version: 1,
+            enabled: true,
+            data: Vec::new(),
+        }))
+    }
+
+    fn on_peer_capability(
+        &self,
+        _network: NetworkId,
+        _peer: EndpointId,
+        _capability: &PluginCapability,
+    ) -> Result<(), PluginError> {
+        Ok(())
+    }
+
+    fn on_peer_link(&self, _network: NetworkId, peer: EndpointId, link: SharedLink) {
+        self.links.lock().unwrap().insert(peer, link);
+    }
+
+    fn on_peer_gone(&self, _network: NetworkId, peer: EndpointId) {
+        self.links.lock().unwrap().remove(&peer);
+    }
+
+    fn on_network_deactivated(&self, _network: NetworkId) {}
+}
+
+type Blocked = Arc<Mutex<HashSet<EndpointId>>>;
+
+async fn member(
+    discovery: &SharedMemoryDiscovery,
+    plugins: &[Arc<Carrier>],
+    blocked: &Blocked,
+) -> TestAgent {
+    let plugins: Vec<_> = plugins.to_vec();
+    let blocked = Arc::clone(blocked);
+    TestAgent::spawn_with(
+        move |config| {
+            let config = config.with_unreachable_data_peers(blocked);
+            plugins
+                .into_iter()
+                .fold(config, |config, plugin| config.with_plugin(plugin))
+        },
+        discovery,
+    )
+    .await
+    .unwrap()
+}
+
+async fn exchange(from: &SharedLink, to: &SharedLink, payload: &'static [u8]) {
+    from.send(Bytes::from_static(payload)).unwrap();
+    let got = tokio::time::timeout(tsunagi::testing::DEADLINE, to.recv())
+        .await
+        .expect("the datagram should arrive")
+        .expect("the link stays open");
+    assert_eq!(got, Bytes::from_static(payload));
+}
+
+#[tokio::test]
+async fn a_tunnel_crosses_a_member_that_shares_no_protocol_with_either_end_and_moves_to_a_direct_link_by_itself()
+ {
+    // A and B share one protocol and nothing else. C shares a different
+    // one with each, so every link here is of a different kind and the
+    // middle has never heard of what A and B speak. A and B cannot reach
+    // each other directly, which is the case a blocked UDP path produces.
+    let discovery = SharedMemoryDiscovery::new();
+    let (name, secret) = network("mixed-transports");
+
+    let blocked_a: Blocked = Arc::default();
+    let blocked_b: Blocked = Arc::default();
+    let a_shared = Carrier::new("shared");
+    let b_shared = Carrier::new("shared");
+    let a = member(
+        &discovery,
+        &[Carrier::new("a-and-c"), Arc::clone(&a_shared)],
+        &blocked_a,
+    )
+    .await;
+    let b = member(
+        &discovery,
+        &[Carrier::new("c-and-b"), Arc::clone(&b_shared)],
+        &blocked_b,
+    )
+    .await;
+    let c = member(
+        &discovery,
+        &[Carrier::new("a-and-c"), Carrier::new("c-and-b")],
+        &Blocked::default(),
+    )
+    .await;
+    let (a_id, b_id, c_id) = (
+        a.agent.endpoint_id(),
+        b.agent.endpoint_id(),
+        c.agent.endpoint_id(),
+    );
+    blocked_a.lock().unwrap().insert(b_id);
+    blocked_b.lock().unwrap().insert(a_id);
+
+    let network_id = a.agent.join_network(&name, &secret).await.unwrap();
+    b.agent.join_network(&name, &secret).await.unwrap();
+    c.agent.join_network(&name, &secret).await.unwrap();
+    for agent in [&a, &b, &c] {
+        wait_for_peers(&agent.agent, network_id, 2).await;
+    }
+
+    // The tunnel comes up through C, and data goes both ways.
+    let to_b = wait_until("a has a link to b", || async { a_shared.link(b_id) }).await;
+    let to_a = wait_until("b has a link to a", || async { b_shared.link(a_id) }).await;
+    exchange(&to_b, &to_a, b"a to b, sealed").await;
+    exchange(&to_a, &to_b, b"b to a, sealed").await;
+
+    // The status says what is true: online, and through whom.
+    let status = a.agent.network_status(network_id).await.unwrap();
+    let b_peer = status.peers.iter().find(|p| p.endpoint_id == b_id).unwrap();
+    assert_eq!(b_peer.data_path, DataPath::Relayed { hops: 2, via: c_id });
+    let c_peer = status.peers.iter().find(|p| p.endpoint_id == c_id).unwrap();
+    assert!(matches!(&c_peer.data_path, DataPath::Direct { transport } if transport == "a-and-c"));
+    let b_member = wait_until("a lists b as a member", || async {
+        let status = a.agent.network_status(network_id).await.ok()?;
+        status.members.into_iter().find(|m| m.endpoint_id == b_id)
+    })
+    .await;
+    assert!(b_member.online);
+    let carried = c.agent.network_status(network_id).await.unwrap().relay;
+    assert!(carried.forwarded >= 2, "{carried:?}");
+
+    // The direct path becomes possible: the same link carries on, now
+    // without C, and nobody has to do anything about it.
+    blocked_a.lock().unwrap().clear();
+    blocked_b.lock().unwrap().clear();
+    wait_until("a reaches b directly", || async {
+        let status = a.agent.network_status(network_id).await.ok()?;
+        let peer = status.peers.iter().find(|p| p.endpoint_id == b_id)?;
+        matches!(&peer.data_path, DataPath::Direct { transport } if transport == "shared")
+            .then_some(())
+    })
+    .await;
+    let forwarded = c
+        .agent
+        .network_status(network_id)
+        .await
+        .unwrap()
+        .relay
+        .forwarded;
+    exchange(&to_b, &to_a, b"direct now").await;
+    assert!(
+        Arc::ptr_eq(&to_b, &a_shared.link(b_id).unwrap()),
+        "the tunnel's link is the one it always had"
+    );
+    assert_eq!(
+        c.agent
+            .network_status(network_id)
+            .await
+            .unwrap()
+            .relay
+            .forwarded,
+        forwarded,
+        "nothing goes through C any more"
+    );
+
+    a.stop().await;
+    b.stop().await;
+    c.stop().await;
+}
+
+#[tokio::test]
+async fn a_name_belongs_to_the_member_that_claimed_it_first_on_every_member() {
+    let discovery = SharedMemoryDiscovery::new();
+    let (name, secret) = network("first-claim");
+    let spawn = |hostname: &'static str| {
+        let discovery = discovery.clone();
+        async move {
+            TestAgent::spawn_with(move |config| config.with_hostname(hostname), &discovery)
+                .await
+                .unwrap()
+        }
+    };
+
+    let first = spawn("music").await;
+    let network_id = first.agent.join_network(&name, &secret).await.unwrap();
+    let first_id = first.agent.endpoint_id();
+    wait_until("the first claim is signed", || async {
+        let status = first.agent.network_status(network_id).await.ok()?;
+        status
+            .members
+            .iter()
+            .any(|m| m.endpoint_id == first_id && m.hostname.as_deref() == Some("music"))
+            .then_some(())
+    })
+    .await;
+
+    // Whatever the ids turn out to be, the later one does not take it.
+    let second = spawn("music").await;
+    let third = spawn("studio").await;
+    second.agent.join_network(&name, &secret).await.unwrap();
+    third.agent.join_network(&name, &secret).await.unwrap();
+    let second_id = second.agent.endpoint_id();
+    for agent in [&first, &second, &third] {
+        wait_for_peers(&agent.agent, network_id, 2).await;
+    }
+
+    for (viewer, label) in [(&first, "first"), (&second, "second"), (&third, "third")] {
+        let status = wait_until(&format!("{label} sees both claims"), || async {
+            let status = viewer.agent.network_status(network_id).await.ok()?;
+            // The roster is the authors of signed records, so a member
+            // being in it means its claim has arrived.
+            let both = [first_id, second_id]
+                .iter()
+                .all(|id| status.members.iter().any(|m| m.endpoint_id == *id));
+            both.then_some(status)
+        })
+        .await;
+        let holder = status
+            .members
+            .iter()
+            .find(|m| m.endpoint_id == first_id)
+            .unwrap();
+        let loser = status
+            .members
+            .iter()
+            .find(|m| m.endpoint_id == second_id)
+            .unwrap();
+        assert_eq!(holder.hostname.as_deref(), Some("music"), "{label}");
+        assert_eq!(loser.hostname, None, "{label}: no name for the later one");
+        let conflict = loser.hostname_conflict.as_ref().expect(label);
+        assert_eq!(conflict.name, "music");
+        assert_eq!(conflict.holder, first_id);
+        assert!(holder.hostname_conflict.is_none(), "{label}");
+        // Nothing about being second makes it less of a member.
+        assert!(
+            loser.online || viewer.agent.endpoint_id() == second_id,
+            "{label}"
+        );
+    }
+
+    // The later one is told so itself, and keeps working.
+    let own = second.agent.network_status(network_id).await.unwrap();
+    let conflict = own.hostname_conflict.expect("told its name is taken");
+    assert_eq!(
+        (conflict.name.as_str(), conflict.holder),
+        ("music", first_id)
+    );
+    assert!(
+        first
+            .agent
+            .network_status(network_id)
+            .await
+            .unwrap()
+            .hostname_conflict
+            .is_none()
+    );
+
+    first.stop().await;
+    second.stop().await;
+    third.stop().await;
+}

crates/tsunagi-tcp-tls/Cargo.toml

@@ -8,7 +8,7 @@ license.workspace = true
 repository.workspace = true
 
 [dependencies]
-tsunagi = { path = "../tsunagi", version = "0.1.0" }
+tsunagi-core = { path = "../tsunagi-core", version = "0.1.0" }
 iroh.workspace = true
 tokio = { workspace = true, features = ["net", "io-util", "time", "sync", "macros"] }
 rustls = "0.23"
@@ -33,7 +33,7 @@ netdev = "0.46"
 caps = "0.5"
 
 [dev-dependencies]
-tsunagi = { path = "../tsunagi", features = ["testing"] }
+tsunagi-core = { path = "../tsunagi-core", features = ["testing"] }
 tempfile.workspace = true
 tracing-subscriber.workspace = true