# Ultra Mesh Network

Ultra Mesh Network is a small, user-space mesh for macOS. Every running laptop gets a stable IPv6-looking overlay address, discovers nearby nodes over regular Wi-Fi and Apple peer-to-peer Wi-Fi, and can relay encrypted traffic for nodes that are not directly connected.

It does **not** install a virtual network interface or replace normal IP networking. Use `umn ping`, the text commands, or the local SOCKS5 proxy to reach mesh addresses.

## Requirements and installation

- macOS 14 or newer
- Apple Command Line Tools with Swift 6
- Wi-Fi enabled on both Macs

Copy this project to each laptop and run:

```sh
./scripts/test.sh
./scripts/install.sh
umn status
umn address
```

The installer builds locally, copies `umn` and `umnd` to `~/.local/bin`, and starts `umnd` as a per-user LaunchAgent. It never needs root. If prompted, allow local-network access. The identity and configuration live in `~/Library/Application Support/UltraMesh`.

Use `./scripts/uninstall.sh` to remove the binaries and LaunchAgent. It deliberately preserves the identity so reinstalling keeps the same mesh address.

For development, run `swift run umnd` in one terminal and `swift run umn status` in another.

## Text communication

On the receiving laptop:

```sh
umn address
umn firewall allow 7000 --from any
umn text listen 7000
```

On the sender:

```sh
umn ping <receiver-mesh-address>
umn text send <receiver-mesh-address> 7000 "hello over the mesh"
```

Replace `any` with a specific mesh address to restrict the port. Opening a firewall port is not sufficient by itself: a local service must also be bound. When `umn text listen` exits, the binding disappears but the firewall rule remains.

Useful diagnostics:

```sh
umn peers
umn routes
umn firewall list
umn alias set alice <mesh-address>
umn ping alice.mesh
```

Aliases are stored locally and are not claimed network-wide.

## HTTP and HTTPS

Run a local server and expose it on a logical mesh port:

```sh
# Host laptop
python3 -m http.server 8080 --bind 127.0.0.1
umn firewall allow 80 --from any
umn expose 80 --to 127.0.0.1:8080
```

Start the client-side proxy:

```sh
umn alias set host <host-mesh-address>
umn proxy --listen 127.0.0.1:1080
curl --proxy socks5h://127.0.0.1:1080 http://host.mesh/
```

The proxy implements SOCKS5 `CONNECT` and binds only to loopback. A browser can use the same proxy after its SOCKS settings are pointed at `127.0.0.1:1080` with proxy-side DNS enabled.

HTTPS is passed through unchanged. The web server remains responsible for its TLS certificate, and a self-signed certificate will still produce the usual trust warning.

## Design and current limits

- Bonjour and Network.framework discover peers over infrastructure and Apple peer-to-peer Wi-Fi (`includePeerToPeer`). New routes recover automatically when an access-point path disappears while Wi-Fi remains enabled.
- Signed link-state announcements and shortest-hop routing support multi-hop topologies. The implementation is bounded and tested for 32 live nodes and 16 hops.
- Service payloads are authenticated and encrypted end-to-end with Curve25519, HKDF-SHA256, and ChaCha20-Poly1305. Relays see routing metadata but cannot read ports or content.
- Streams use sequence numbers, acknowledgements, retransmission, and a 60-second recovery window. An active stream can continue after a route change if another path appears within that window.
- The endpoint firewall defaults to ping-only. Transit traffic is relayed independently of endpoint firewall rules.
- Text is limited to 4 KiB. A logical stream is limited to 1 MiB total and the daemon supports at most 32 simultaneous streams.
- There is no durable offline queue: a new operation with no live route fails immediately.
- Membership is open. Identities are self-authenticating, but there is no global authority, revocation service, or Sybil resistance yet.
- Apple peer-to-peer Wi-Fi works only between Apple devices. The documented mesh protocol is transport-independent so other bearers can be added later.

The on-wire details are in [docs/protocol.md](docs/protocol.md).