95 lines
4.0 KiB
Markdown
95 lines
4.0 KiB
Markdown
# 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).
|