inital commit

2026-08-31 15:55:09 -05:00
commit e71b3ada71
22 changed files with 1783 additions and 0 deletions
@@ -0,0 +1,94 @@
+# 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).