diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..dfdb8b7 --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +*.sh text eol=lf diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 50538a9..e23647d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -6,6 +6,37 @@ on: pull_request: jobs: + installers: + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest, ubuntu-24.04-arm, macos-15, windows-latest] + runs-on: ${{ matrix.os }} + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: '3.x' + - name: Native Unix installer fixtures (no node starts) + if: runner.os != 'Windows' + run: python tests/installers.py + - name: Native Windows PowerShell 5.1 installer fixtures (no node starts) + if: runner.os == 'Windows' + shell: powershell + run: python tests/installers.py --powershell powershell + - name: Native PowerShell 7 installer fixtures (no node starts) + if: runner.os == 'Windows' + shell: pwsh + run: python tests/installers.py --powershell pwsh + # The real v0.5.3 asset over HTTPS into a temp dir; --help only after the checksum. + - name: Live release download (checksum, then --help; no node) + if: runner.os != 'Windows' + run: python tests/installers.py --live-release Installers.test_live_release_https + - name: Windows PowerShell 5.1 live release download (checksum, then --help; no node) + if: runner.os == 'Windows' + shell: powershell + run: python tests/installers.py --powershell powershell --live-release Installers.test_live_release_https + test-and-verify: runs-on: ubuntu-latest steps: @@ -22,7 +53,7 @@ jobs: strategy: fail-fast: false matrix: - os: [macos-14, windows-latest] + os: [macos-15, windows-latest] runs-on: ${{ matrix.os }} steps: - uses: actions/checkout@v4 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 6425027..b73fdf7 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -32,7 +32,7 @@ jobs: fail-fast: false matrix: include: - - os: macos-14 + - os: macos-15 target: aarch64-apple-darwin - os: ubuntu-latest target: x86_64-unknown-linux-musl diff --git a/.gitignore b/.gitignore index 2b0b1d7..f1fbfea 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ /target +/.installer-tests-*/ /bin .DS_Store *.swp diff --git a/README.md b/README.md index 95e03ac..8af8e24 100644 --- a/README.md +++ b/README.md @@ -1,657 +1,40 @@ -# Dialtone User Guide +# Dialtone -`dialtone` is a single-binary Rust + **Iroh 1.3** peer-to-peer mesh control plane, 3D tactical HUD & terminal `top` monitor, content-addressed blob store (`iroh-blobs`), and process supervisor. It runs without SSH, Git, or Tailscale/VPN runtime dependencies. +Install **v0.5.3** on Linux or macOS: -This guide uses the project's [domain language](goal.md#domain-language): one word per concept (Node, NodeId, Peer, Mesh, Channel, Secret, Allowlist, Invite, Seed, Message, Beat, Inventory, Stats, Blob, Digest, Store, Ticket, Program, Process, Probe, HUD, API). - -```text -$ dialtone --help -usage: dialtone [action] [flags] - -Single-binary Iroh 1.3 + Rust mesh control plane, 3D tactical HUD, blob store & daemon. -Running `dialtone` with no arguments boots in dependency order and prints the local Web HUD URL. - -actions: - up Start the node: HUD -> store -> Iroh QUIC -> mesh - join Join a channel with an invite from any member (dialtone-invite-v2:...), - install this binary and start the node at login (--once: only join) - join Unlock (or start) a channel with its secret - secret Generate a new channel secret (dt-...) - allowlist [list|add|remove] [] Manage the allowlist in ~/.dialtone/config.json - blob [share|pull] Share a file or text as a blob, or pull a blob by ticket - link export --udp|--tcp Offer a local source to peers over a direct link - link import / --udp|--tcp Open a peer's source and deliver it here - link [list|close ] Show links (path direct or relay, Rtt, packets), or close one - invite [--ttl 24h] Make an invite any node can join with until it expires (max 30d) - daemon [install|status] install: put this binary in ~/.dialtone/bin, register the login - service and start the node (a running one restarts into it) - probe [--all] Run one probe now: the gossip checks (MSH, NBR, BEAT; nodes run them - every 30s), and with --all the store, pulls, programs and security - (STO, PUL, PRC, SEC) - devices [--json] List the devices connected to this machine (cameras, mics, keyboards, ...) - status Print this node's NodeId and transport report - help Show this help - -flags: - --node Node name (default: saved config or hostname) - --listen HUD and API listen address (default: 127.0.0.1:8788) - --api-token Explicit API bearer token for POST routes (default: ~/.dialtone/api-token) - --channel Channel name (default: dialtone) - --secret Channel secret (or set DIALTONE_SECRET) - --ttl TTL for 'dialtone invite' (e.g. 15m, 1h, 7d; default: 24h) - --addr Direct address for 'dialtone allowlist add' (repeatable) - --force Pull over QUIC even if the blob is already in the store - --udp 'dialtone link': where the source sends (export) or packets go (import) - --tcp 'dialtone link': the service to connect to (export) or listen on (import) - --json Print JSON ('devices', 'invite', 'link list') - --once 'up': boot, beat once and exit; 'join': only join, start nothing - --all 'dialtone probe': also test the store, pulls, programs and security - -transport (the default: relays on, no public DNS or DHT, Tailscale addresses left out): - --private-mesh No relays: dial peers only at their direct addresses - --relay-only Advertise only the relay, no direct addresses - --relay-url Use this Iroh relay instead of the public ones (repeatable) - --quic-port Bind the QUIC endpoint to this UDP port - --lan Also find peers on the local network (mDNS) - --allow-tailnet Also use Tailscale addresses +```sh +sh -c 's=$(curl -fsSL https://raw.githubusercontent.com/timcash/dialtone/main/install.sh) && eval "$s"' ``` -HUD keys (at http://127.0.0.1:8788): - -```text - Up / Down Arrow Zoom camera in/out across Layers 1..5 (GLOBE -> PROCESS) - Left / Right Arrow Step backward/forward through the 5-step tour (MSH BLB PRC NET DEV) and nodes - Double-Click Node / Row Zoom into focused node symbol (resets to L1 GLOBE after L5) - Click [1 MSH] .. [5 DEV] in Bottom CC Jump directly to any capability step in the live Closed Captions -``` - ---- - -## Quick Start (60 Seconds) - -### 1. Download (or Build) the Single Binary - -```bash -# macOS (Apple Silicon) -curl -fsSL https://github.com/timcash/dialtone/releases/latest/download/dialtone-macos-arm64 -o dialtone && chmod +x dialtone - -# Linux (x86_64 static musl) -curl -fsSL https://github.com/timcash/dialtone/releases/latest/download/dialtone-linux-x86_64 -o dialtone && chmod +x dialtone - -# Or build from source with Rust -cargo build --release && cp target/release/dialtone ./dialtone -``` +Windows x64 (PowerShell 5.1 or 7; Windows 10 1803+, Windows 11, or Server 2019+ for the built-in `curl.exe`): ```powershell -# Windows (PowerShell) -Invoke-WebRequest -Uri https://github.com/timcash/dialtone/releases/latest/download/dialtone-windows-x86_64.exe -OutFile dialtone.exe -``` - -### 2. Boot a Node & Open the 3D Tactical HUD - -```bash -./dialtone up --node node-alpha +$s = curl.exe -fsSL https://raw.githubusercontent.com/timcash/dialtone/main/install.ps1 | Out-String; if ($LASTEXITCODE) { throw 'install.ps1 download failed' }; iex $s ``` -Open **`http://127.0.0.1:8788`** in your browser to view the live 3D mesh topology and terminal `top` stats table. +Dialtone is a single-binary peer-to-peer mesh, local web HUD, blob store, and process supervisor. Installation verifies SHA-256 and places only the executable in `~/.local/bin` (`$HOME\.local\bin` on Windows). It needs no administrator privileges and starts nothing. -### 3. Join Other Computers with an Invite +Use the full path first (or [add the directory to PATH](docs/install.md#path)): -On the first node, start a channel and make an invite (valid 24h by default, up to `--ttl 30d`): - -```bash -./dialtone join "$(./dialtone secret)" --node node-alpha --once # a new channel (keep the secret if you want it) -./dialtone up --node node-alpha # leave it running -./dialtone invite --ttl 7d # prints dialtone-invite-v2:... -``` - -Any other computer joins with the invite alone, no build tools and no NodeIds exchanged: download the one binary for it from the [latest release](https://github.com/timcash/dialtone/releases/latest) and run `join`. - -```bash -# Linux x86_64 (arm64: dialtone-linux-arm64; macOS Apple silicon: dialtone-macos-arm64) -curl -fsSLo dialtone https://github.com/timcash/dialtone/releases/latest/download/dialtone-linux-x86_64 -chmod +x dialtone && ./dialtone join 'dialtone-invite-v2:...' +```sh +"$HOME/.local/bin/dialtone" --help +"$HOME/.local/bin/dialtone" up ``` ```powershell -# Windows x86_64 -curl.exe -fsSLo dialtone.exe https://github.com/timcash/dialtone/releases/latest/download/dialtone-windows-x86_64.exe -.\dialtone.exe join 'dialtone-invite-v2:...' -``` - -`dialtone join ` joins the channel, copies itself to `~/.dialtone/bin`, installs the node as a login service (launchd, systemd `--user`, or a Windows logon task) and starts it, so the downloaded file can be deleted. Where no login service can run (a container without systemd, say) the node starts now and keeps itself running: it restarts after updates and crashes, but not after a reboot. Run it again with a newer binary and the running node restarts into it. Options: `--node ` (default: the hostname), `--listen `. With `DIALTONE_STATE_DIR` set (a second node on one machine, or a trial) everything stays in that folder and the node starts now but not at login. Each release also has a `.sha256` next to every binary, and once installed a node only ever updates to binaries the release key signed. `dialtone join --once` only records the channel. - -### 4. Optional: Install as a Background Login Service & Check the Mesh - -```bash -# Install this binary as a user-level OS service (launchd / systemd --user / Windows logon task) and start it -./dialtone daemon install - -# Check the running node: mesh, beats, store, pulls from peers, programs and security -./dialtone probe --all -``` - ---- - -## 1. Installation & Boot Pipeline - -### Pre-Compiled Release Assets - -Every GitHub Release publishes standalone, size-optimized single-file executables with all runtime assets and the Web UI compiled directly into the binary: - -| Platform | Release Asset | -| :--- | :--- | -| **macOS (Apple Silicon)** | `dialtone-macos-arm64` | -| **Linux (x86_64, static musl)** | `dialtone-linux-x86_64` | -| **Linux (ARM64 / Edge)** | `dialtone-linux-arm64` | -| **Windows (x86_64)** | `dialtone-windows-x86_64.exe` | - -### 5-Stage Boot Sequence - -Running `./dialtone` (with no arguments, or `./dialtone up`) boots 5 subsystems in strict dependency order and starts the local Web HUD immediately: - -```text -[BOOT 1/5] Local Runtime & Stdout Logger ................. [READY] (node=node-alpha, os=macos/aarch64) -[BOOT 2/5] Local Web HUD & Config Server ................. [READY] http://127.0.0.1:8788 -[BOOT 3/5] Content-Addressed Blob Store (iroh-blobs) ..... [READY] ~/.dialtone/blobs -[BOOT 4/5] Iroh 1.3 QUIC Endpoint (No-Tailnet NIC) ....... [READY] id=a67ff536b0f9.. ip=192.168.1.40 -[BOOT 5/5] Gossip Mesh & Channel Secret ................ [READY] channel=ch-7981c39da07e peers=2 -``` - -- **Port Auto-Fallback**: Defaults to `127.0.0.1:8788` (override with `--listen `). If `8788` is in use and `--listen` was not explicitly forced, `dialtone` automatically scans `127.0.0.1:8788..=8799` (falling back to an OS-assigned port). -- **One-shot run**: `./dialtone up --once` boots, prints one beat and exits. Next to a running node it uses a private store and leaves the config alone. - ---- - -## 2. Local Web HUD, Terminal `top` UI & Stats - -Open **`http://127.0.0.1:8788`** to access the embedded tactical HUD: - -- **Terminal `top` table**: mesh-wide rows (`MSH`, `NET`, `PRB`, `CPU`, `MEM`, `DSK`), where `PRB` counts each probe check passing across nodes (`MSH` `NBR` `BEAT` `PUL` `PRC`), then one row per node (`NODE`, `ARCH`, `CPU`, `MEM`, `DSK`, `IP/PATH`, `RX/TX`, `LNK`, `RTT`, `JIT`, `PROC`, `PRB`), then the focused node's devices. -- **Threshold colours**: values stay greyscale when nominal, turn amber at the warning level and red at the error level (CPU 75% / 92%, memory 78% / 92%, disk 82% / 94%). -- **Tour**: visits every node and steps through `MSH` (mesh), `BLB` (store and blob pulls), `PRC` (probe program), `NET` (beats and Rtt) and `DEV` (devices); the closed captions narrate that node's latest probe. -- **Interactive 3D Mesh Topology**: Drag to orbit, scroll to zoom, or click any peer node to inspect its live QUIC links and metadata. -- **Menu** (bottom-right button): tour and camera controls, zoom layers, display toggles, and — under - *05 // Mesh setup (CLI)* — the commands for creating a mesh, inviting and allowing nodes. The page holds no API - token, so mesh changes are made with the CLI. -- **Endpoints the HUD uses**: `GET /` (the page), `GET /hud/...` (its static files) and `GET /api/mesh` (polled - every 1.5s). - ---- - -## 3. Starting a Gossip Mesh from Scratch - -Because `dialtone` ships with **zero hardcoded mesh peers** and enforces a **deny-by-default peer allowlist** + **Argon2id / XChaCha20-Poly1305 encrypted channel**, a brand-new node boots into an isolated `dialtone:locked-standby` topic until you configure a channel secret and authorize your peers. - -Below are the two ways to seed a new multi-node mesh from scratch (using generic example nodes `node-alpha` and `node-beta`). - -### Option A: An Open Channel with Invites (Simplest) - -A channel whose nodes have an **empty allowlist** is open: any node holding the channel keys is a member, and nobody lists anybody's NodeId. Members hand the keys out for **invites**. - -1. On `node-alpha`, start the channel and the node, then make an invite: - - ```bash - ./dialtone join "$(./dialtone secret)" --node node-alpha --once - ./dialtone up --node node-alpha - ./dialtone invite --ttl 24h - ``` - -2. On any other host, join with the invite (or use the install script above): - - ```bash - ./dialtone join "dialtone-invite-v2:..." --node node-beta - ``` - -**How an invite works.** `dialtone invite` asks the running node for one (`POST /api/invites`). It names the channel, an expiry and up to four members to present it to (that node, then its seeds; each with its NodeId, home relay and direct addresses), under a MAC with the channel's `auth_key`; it carries **no keys**. `dialtone join ` opens one QUIC stream to the first named member that answers (ALPN `dialtone/join/1`) and presents it; the member checks the MAC and the expiry and answers with the channel keys and the same list of seeds. So an invite works while any one of its members is up. The QUIC handshake proves the answer comes from the NodeId the invite names. The joining node saves the keys (`config.json`, `0600`), clears any allowlist and starts. - -- An invite works for any number of nodes until it expires, then for none. Make a new one with `dialtone invite`. -- The node that made the invite must be online when someone joins with it. -- Once joined, a node keeps the keys. To remove members, start a new channel (a new secret) and invite the nodes that should stay. -- A channel with an allowlist refuses invites; its nodes keep authorizing each other by NodeId (Option B). - ---- - -### Option B: Explicit Allowlist Provisioning Across N Nodes (Deterministic / Automated) - -If you are provisioning 2, 3, or more hosts via a setup script or SSH, you can pre-populate each node's allowlist directly using `dialtone status`, `dialtone join --once`, and `dialtone allowlist add`: - -```bash -# 1. On EVERY host, initialize its persistent Ed25519 identity (~/.dialtone/iroh-secret-key) -# and record its 64-character hex "node_id": -./dialtone status --node - -# 2. On ONE host, generate the shared channel secret: -./dialtone secret -# -> e.g. dt-R9xK4mP7vQ2wL8nJ5tB3yF6hC1zX0sW9_AbCdEfGhIj - -# 3. On EVERY host, derive the Argon2id channel keys into ~/.dialtone/config.json: -./dialtone join "" --node --once - -# 4. On EVERY host, authorize every peer's NodeId (adds to allowlist & seeds): -./dialtone allowlist add -./dialtone allowlist add -./dialtone allowlist add - -# Verify the local allowlist and seeds: -./dialtone allowlist list - -# 5. Start dialtone in the foreground (or install as a persistent background service): -./dialtone up --node -# or: -./dialtone daemon install -``` - -### Step 4 — Verify Mesh Convergence - -Within a few seconds of starting, verify that all nodes are exchanging encrypted messages (`dialtone.iroh.envelope.v5`) and incrementing their beat `counter`. All nodes must run the same envelope version, so upgrade a mesh together: - -```bash -# Check discovered peers and beat counters via the local HTTP API -curl -s http://127.0.0.1:8788/api/state | jq '.nodes[] | {node, role, node_id, counter}' - -# Check the 5 boot stages and active channel fingerprint (ch-...) -curl -s http://127.0.0.1:8788/api/config | jq '{node, channel_fingerprint: .mesh_config.channel_fingerprint, boot_stages}' -``` - -Or open **`http://127.0.0.1:8788`** in your browser to view the live 3D topology and terminal `top` table. - ---- - -## 4. Channel Security, Peer Allowlist & Control API Reference - -**How the mesh is protected** - -- **Open channel or allowlist, at the handshake.** With an empty allowlist the channel is open: gossip and join (`dialtone/join/1`) accept any NodeId, gossip frames that do not open with the channel keys are dropped (and cost their sender its score), and fetch, blobs and link accept only members, NodeIds this node has had a valid message from. With NodeIds listed, every QUIC connection (gossip and blobs, in and out) is closed right after the TLS handshake unless the remote NodeId is on the allowlist. `dialtone allowlist add/remove` edits `~/.dialtone/config.json`; a running node picks the change up within 5 seconds, no restart. -- **Signed messages.** Nodes gossip three typed messages (see [Scaling the mesh](#scaling-the-mesh)): a **Beat** (liveness, load, the node's probe checks and its gossip neighbors with their Rtt), an **Inventory** (the node's processes, services and details) when it changes, and a **Deploy** (a program the node deploys to the mesh, or removes from it). Each message is signed with the sender's Key and encrypted with the channel keys. A node drops messages whose signature does not match the NodeId they claim, messages from NodeIds not on its allowlist (when it has one), and replays (each node's `sent_unix_ms` must increase and be within 5 minutes of local time — keep node clocks roughly in sync). -- **No process secrets on the wire.** An inventory lists each process without its `env` or `args`. -- **Deploys are announced, and only targeted nodes pull.** `POST /api/processes/blob` with `"deploy_to_mesh": true` (and optionally `"deploy_targets": ["node-name", "", ...]`) makes the origin gossip a signed **Deploy** naming the program, its blob ticket and its targets (every node when none are named). A targeted node pulls the program, from up to three peers whose inventories say they already run it (gossip neighbors first) and then from the origin, after a random delay of up to one beat interval so a large mesh does not pull at once; it checks the SHA-256, stages and starts it. Nothing auto-deploys from inventories, and no node's probe program is ever deployed. -- **Deploys follow their origin.** A copy is never announced further. It is removed when the origin announces the program removed (removing it on the origin), no longer targets this node, or stops announcing it for 30 minutes while still in the mesh. The origin announces every change at once, and all its deploys again every 10 minutes and soon after a node joins (removed ones for an hour), so a node that was away catches up through gossip alone. -- **Deploys only from the allowlist.** A Deploy is admitted only from an allowlisted signer, and blob pulls use the node's own endpoint, so each provider's allowlist decides. -- **HUD.** The page carries no API token; a per-response Content-Security-Policy nonce lets only its own scripts run. three.js and h3-js are compiled into the binary and served from `/hud/vendor/`, so the HUD loads nothing from the Internet. - -### Unlock & Join the `"dialtone"` Channel (`join` & `secret`) - -The `"dialtone"` channel (and any custom `--channel `) is **secret-protected and end-to-end encrypted**: -- Booting `dialtone` without a configured secret places the node on an isolated per-node standby topic (`dialtone:locked-standby`) and does **not** dial mesh seeds until unlocked. -- **Minimum Secret Strength**: Secrets must be at least 16 characters long with multiple character classes and `>= 8` unique characters; weak or dictionary secrets (`"dialtone"`, `"dialtone2"`, `"secret123"`, `"default"`) are rejected. Run `./dialtone secret` to generate a CSPRNG 256-bit secret (`dt-...`). -- **Argon2id Key Derivation (`v2`) & XChaCha20-Poly1305 Gossip Encryption**: - 1. `dialtone` derives three domain-separated 32-byte subkeys (`topic_id`, `auth_key`, `enc_key`) from `(channel, secret)` using **Argon2id** (`m=19456 KiB, t=2, p=1`). - 2. Only the derived subkey bundle (`derived_keys`) is persisted in `~/.dialtone/config.json` (`0600` permissions) — the plaintext secret is **never** written to disk. Any legacy `~/.dialtone2/config.json` is automatically migrated and scrubbed on startup. - 3. Every message broadcast over `iroh-gossip` is signed with the sender's Key and encrypted with `enc_key` using **XChaCha20-Poly1305** (`dialtone.iroh.envelope.v5`: a binary frame, random 24-byte nonce). Unencrypted or unsigned frames are dropped. -- **Deny-by-Default Peer Allowlist (`allowlist`)**: - - On the main `"dialtone"` channel, inbound peers are **denied by default** unless their `NodeId` is listed in the host's local `~/.dialtone/config.json` (`allowlist`), even if `--invite` is passed. - - Manage the allowlist via CLI: - ```bash - ./dialtone allowlist list - ./dialtone allowlist add - ./dialtone allowlist add --addr 192.168.1.50:19440 - ./dialtone allowlist remove - ``` -- **Expiring invites (`invite`)**: - - The running node makes an invite (`dialtone-invite-v2:...`) that any node can join with until it expires: - ```bash - ./dialtone invite --ttl 15m - ``` - -```bash -# Generate a high-entropy 256-bit channel secret -./dialtone secret - -# Unlock the default 'dialtone' channel with a secret (updates a running local daemon live, or boots a new one) -./dialtone join - -# Redeem a single-use invite while joining -./dialtone join --invite dialtone-invite-v1: - -# Save derived channel keys to ~/.dialtone/config.json (0600 permissions) and exit immediately -./dialtone join --once -``` - -### Local HTTP Control API Bearer Authentication (`~/.dialtone/api-token`) - -All state-changing `POST` routes on the local HTTP control plane require bearer token authentication (`Authorization: Bearer ` or `X-Dialtone-Token: `): -- On first boot, `dialtone` generates a 32-byte random token in `~/.dialtone/api-token` (`0600` permissions). Override with `--api-token ` or `DIALTONE_API_TOKEN`. -- Binding `--listen` to a non-loopback address (e.g. `0.0.0.0:8788`) is refused unless an explicit `--api-token` or `DIALTONE_API_TOKEN` is configured. -- The HTTP server processes requests concurrently on bounded process threads (`MAX_CONCURRENT_HTTP_CONNECTIONS = 32`) with a 2-second socket read/write timeout and 2 MiB body size limit. - -```bash -API_TOKEN=$(cat ~/.dialtone/api-token) -curl -X POST http://127.0.0.1:8788/api/mesh/join \ - -H "Authorization: Bearer $API_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{"channel":"dialtone","secret":"dt-...","node":"node-alpha"}' -``` - -### Transport Inspection (`status`) - -```bash -# Bind persistent Ed25519 identity (~/.dialtone/iroh-secret-key) and print transport diagnostics -./dialtone status --node node-alpha +& "$HOME\.local\bin\dialtone.exe" --help +& "$HOME\.local\bin\dialtone.exe" up ``` -### Transport & Discovery Flags - -A node never publishes itself to a public directory (Pkarr DNS or Mainline DHT), so its `NodeId` and IP addresses never appear there; the full probe's `SEC` check fails if it ever does. By default it uses the public Iroh relays and leaves Tailscale addresses (`100.64.0.0/10`, `fd7a:115c:a1e0::/48`) out of what it advertises, binding QUIC to the primary physical IPv4 interface. - -| Flag | Behavior | -| :--- | :--- | -| `--private-mesh` | No relays: peers are dialed only at the direct `ip:port` addresses from `allowlist add --addr` or invites. | -| `--relay-only` | Strips direct IP addresses from tickets so traffic goes only through the relay (`relay_only` profile). | -| `--relay-url ` | Uses this Iroh relay instead of the public ones (repeatable). | -| `--quic-port ` | Binds the Iroh QUIC UDP socket to a fixed port (e.g. `19440`) so peers can dial it directly. | -| `--lan` | Also finds peers on the local network with mDNS (`lan_only` profile). | -| `--allow-tailnet` | Also advertises Tailscale interface addresses. | - ---- - -## 5. Persistent OS Daemon & Service Units - -`dialtone` can install itself into your user account so it starts automatically on boot/login without requiring `root` or `sudo`. Derived Argon2id channel keys are saved to `~/.dialtone/config.json` (`0600`) and raw secrets are never written to disk or passed on the service command line: - -```bash -# Copy binary to ~/.dialtone/bin/ and register OS login service -./dialtone daemon install - -# Check installation status and saved configuration -./dialtone daemon status -``` - -| Operating System | Installed Service Blob | -| :--- | :--- | -| **macOS** | `~/Library/LaunchAgents/com.timcash.dialtone.plist` (`launchctl load -w`) | -| **Linux** | `~/.config/systemd/user/dialtone.service` (`systemctl --user enable --now dialtone.service`) | -| **Windows** | `~/.dialtone/start-dialtone.cmd` registered in `HKCU\...\Run\DialtoneDaemon` + Scheduled Task `DialtoneDaemon` | - -### Self-update: a new release reaches every node on its own - -A node that runs from `~/.dialtone/bin` (every service install does) updates itself whenever a new release is tagged, and rolls back a release that does not start healthy: - -- **Detect.** Every beat carries the version its node runs. A node asks GitHub for the latest release about once an hour, and as soon as a peer's beat shows a newer one. -- **Trust.** The release workflow signs `dialtone-release.json` (each binary's SHA-256, BLAKE3 hash and size) with the release key, and every binary holds the public key. A binary is installed only if the manifest verifies and the binary matches it, so a binary from a peer is as trusted as one from GitHub. -- **Fetch.** From peers that already run the release on the same OS and architecture (iroh-blobs), else from GitHub. A node that cannot reach GitHub still updates from its peers. -- **A/B install.** The running binary moves aside as `dialtone.prev`, the new one takes its path, and the node exits (code 75) so its service starts the new one. A node with no service (one `dialtone join` could not install, or a bare `nohup dialtone up &`) runs as its own restart loop: it starts the new binary itself, and restarts the node after a crash (2s, doubling to 60s). -- **Trial and rollback.** The new binary is kept once it has run for a minute with gossip joined and, if the old one had neighbors, at least one neighbor. If it is not healthy within 3 minutes, or it fails to start 3 times, `dialtone.prev` takes the path back, the version is marked bad in `~/.dialtone/update.json` (never tried again), and the old binary runs. - -`DIALTONE_AUTO_UPDATE=0` turns it off. A binary run from anywhere else (a development build) never replaces itself. `./dialtone.sh test --only probes` shows the version every test VM runs. `./dialtone.sh test --only rejoin` checks the whole path on the live channel: a node on the previous signed release joins by invite, goes away and rejoins, hears of the newest release in a peer's beat, installs it, restarts and keeps it (about two minutes on the test VMs). - ---- - -## 6. Blob Store - -The store is an iroh-blobs `FsStore` in `~/.dialtone/blobs/` (`blobs.db`, `data/`). Every blob is named by its digest through the tag `sha256/`, which points at its BLAKE3 hash; tagged blobs are kept and garbage collection removes anything untagged (such as an interrupted download). Uploads are checked against their SHA-256 before they are added, and a pulled blob is checked against the ticket's digest before it is tagged. Blobs left in the old one-file-per-digest layout are imported the first time the node starts. A store belongs to one process: one-shot runs (`--once`) next to a running node use a private temporary store. - -### Store, Fetch & Verify Blobs via HTTP - -```bash -API_TOKEN=$(cat ~/.dialtone/api-token) - -# 1. Upload base64 payload into the verified store -BLOB_B64=$(printf '#!/bin/sh\nsleep 30\n' | base64 | tr -d '\n') -curl -X POST http://127.0.0.1:8788/api/blob \ - -H "Authorization: Bearer $API_TOKEN" \ - -H "Content-Type: application/json" \ - -d "{\"bytes_base64\":\"$BLOB_B64\"}" - -# 2. Check blob presence and byte length (HEAD) or download bytes/metadata (GET) -curl -I "http://127.0.0.1:8788/api/blob?sha256=<64-hex-digest>" -curl -s "http://127.0.0.1:8788/api/blob?sha256=<64-hex-digest>" -``` - -### Live Cross-Peer `iroh-blobs` QUIC Share & Pull (`blob share` / `blob pull`) - -Every running `dialtone` daemon attaches `iroh_blobs::BlobsProtocol` to its live QUIC router so peers can share and pull content-addressed blobs directly over QUIC: - -```bash -# On Node A: add a file (or text) to the store and get a ticket for it -./dialtone blob share ./process-script.sh -# -> {"digest": "sha256:...", "ticket_uri": "iroh-blobs://ticket/blob...#sha256:...", ...} - -# On Node B: pull it over QUIC from Node A; its SHA-256 is checked against the ticket before it is kept -./dialtone blob pull "iroh-blobs://ticket/blob...#sha256:..." --force -``` - ---- - -### Self-test loop (Probe) - -Every running node checks the gossip mesh every 30 seconds. These checks read what gossip already brought, so they cost no traffic of their own: - -| Check | What it proves | -| :--- | :--- | -| `MSH` | Every allowlisted peer is in the mesh | -| `NBR` | The node has at least two gossip neighbors (one in a two-node mesh) | -| `BEAT` | Every peer's beats are fresh (within three of its beat intervals) and every peer hears as many nodes as this one | - -A full probe also tests the node's other capabilities, which move data, so it runs only when asked (`dialtone probe --all`, or `POST /api/probe` with `{"all": true}`; `./dialtone.sh test` and `deploy` run one on every test VM): - -| Check | What it proves | -| :--- | :--- | -| `STO` | A fresh blob is written to the store and read back intact | -| `PUL` | Up to 3 peers, chosen at random, each write a fresh blob on request; it downloads over QUIC through the node's downloader, SHA-256 verified | -| `PRC` | The probe program, staged from the store, is running under the supervisor | - -A compact report (the checks, without per-peer results) travels in the node's beats, so each HUD shows every node's results (PRB row, tour steps). Failed checks are logged. Probe blobs are forgotten after use, so the store does not grow. `dialtone probe` (or `POST /api/probe`) runs one immediately; `GET /api/probe` returns the latest. - -### Scaling the mesh - -Gossip is routed the way [libp2p GossipSub](https://docs.libp2p.io/concepts/pubsub/overview/) routes it, on top of iroh-gossip's HyParView membership and Plumtree broadcast tree: - -- **A few neighbors, not every node.** Each node keeps 2 to 5 gossip neighbors. Below two (GossipSub's `D_lo`) it joins up to three known peers chosen at random; nobody dials every other node. A message reaches the whole mesh along the broadcast tree, each node forwarding it once. -- **Gossip only.** Once a node has joined, it talks to the mesh only through gossip: no node fetches from another unless someone asks (a HUD focusing a node, a full probe). The three-node test (`tests/e2e.rs`) checks that no node opens a connection in 20s of steady state. -- **Small, fixed-size beats.** A beat is a compact binary record (postcard, `wire.rs`), about 255 bytes sealed for a healthy node and at most about 310: name, counter, load (CPU, memory, disk, network), coarse location, home relay and two addresses, the probe's checks, the inventory version and up to five gossip neighbors with their Rtt. No seed lists, no per-peer results, nothing that grows with the mesh. Rolling summaries are not gossiped. -- **Rtt for free.** Each neighbor's Rtt is QUIC's own estimate on the gossip connection that is already open, read through a weak handle the allowlist hook keeps (the Paths actor); no ping is sent. So is whether the path is direct or through the relay. -- **Separate topics.** Beats go on the channel's beats topic; inventories are broadcast on its events topic when they change. An inventory leaves out process pids, statuses and restart counts, so a restart does not re-broadcast it. -- **Beat interval from a budget.** Every node hears every beat, so a node beats every `clamp(nodes × 500 B / 4 KB/s, 5, 120)` seconds: about 4 KB/s of incoming beats per node at any size (5s up to 40 nodes, 13s at 100, 120s at 1,000). Freshness checks use each peer's own interval (three of them). iroh-gossip remembers message ids for 6 minutes (three of the longest intervals; its default is 90s), so a beat still travelling is not delivered twice. -- **One-sided links repaired from beats.** iroh-gossip's HyParView can lose the one reply that completes a link. Each beat lists its sender's neighbors; a neighbor whose beats leave this node out twice in a row is joined again. -- **Peer scores.** As in GossipSub, each node scores its peers: credit for messages a neighbor delivered, a squared penalty for invalid frames it delivered. Below −20 a peer is graylisted: what it delivers is dropped, it is not joined, and the node joins other peers when it has fewer than two good neighbors. Failed fetches are counted apart: three recent ones make the node fetch from other peers for a while, never graylist (a restarting peer fails fetches without misbehaving). Every counter decays each beat. `GET /api/net` lists the scores. -- **Details on focus.** What beats leave out (devices, the full probe report, processes with their status, services, the rolling summary, store, full stats and transport) is fetched for the node a HUD focuses (`GET /api/details?node_id=…`, which asks that node over `dialtone/fetch/1` and keeps the answer for 10s). -- **Peers that go silent are forgotten.** A peer pruned from the mesh is no longer a join candidate (seeds stay), so a node short of neighbors does not keep dialing dead peers. -- **Seeds follow the mesh.** About once a minute (every 12 beats) a node saves the peers it hears as its seeds in `config.json`: seeds it still hears stay first, other live peers fill up to 8, silent ones are dropped (a node that hears nobody keeps what it had). A node that restarts after the member it joined through has left still reaches the mesh. - -`./dialtone.sh test --here --only scale --scale N [--secs S]` starts N nodes on this machine, each given 3 random seeds, and reports how long until every node sees all N and the traffic per node (`GET /api/net`: socket bytes from iroh's counters, gossip messages, neighbors, and iroh-gossip's own counts of data frames, duplicates included, and control messages). Measured on one laptop: - -| Nodes | Before | After | -| ---: | :--- | :--- | -| 10 | converged in 4s; 56 Mbit/s in and out per node, 2001 connections opened | converged in 7s; 60 kbit/s per node, 4.6 neighbors | -| 30 | never converged (180s) | converged in 8s; 120 kbit/s per node | -| 50 | — | converged in 19s; 200 kbit/s per node | -| 100 | — | converged in 48s on one overloaded laptop | - -With gossip only and compact beats (envelope v6), 50 nodes on the same laptop converge in 12s at 42.5 kbit/s in per node (14 kbit/s of it gossip payload, 1.33 data frames per message delivered). On the live mesh a node takes in 0.76 kbit/s of gossip payload; the rest of its roughly 11 kbit/s is iroh's own upkeep of relay and paths. - -`./dialtone.sh test --only scale --scale N [--secs S]` does the same across the test VMs: N throwaway nodes on every VM in `fleet.local.env` (each runs the VM's installed binary), one mesh, seeds on any VM, links direct or through the relay. It waits 60s after convergence (`SCALE_WARMUP`), then reports traffic per VM, and stops every scale node afterwards (the VMs' own nodes are left alone); `./dialtone.sh test` ends with it, 10 nodes per VM. On the three VMs (US, Europe, Asia), 10 nodes on each (30 in all) converge in 17s and run at about 61 kbit/s in and out per node, of which 12.5 kbit/s is gossip payload (6 messages a second, 2.14 data frames per message delivered, 4.2 neighbors, none graylisted). Before the fleet moved to VMs, 20 nodes on each of three machines (60 in all) converged in 30 to 50s and settled in one of two states: most at about 420 kbit/s in per node, of which 133 kbit/s is beats (10 messages a second, about 2.1 data frames per message delivered); some at about 850 kbit/s, with 15 messages a second delivered and 2.8 frames each. The extra messages are not yet explained; old beats arriving up to 100s late (seen in node logs as replay rejects) suggest messages coming round again after iroh-gossip forgets their ids. Changing Plumtree's graft timeout made no difference. - -### Direct links (video) - -Gossip carries only what every node needs. Live media goes over a **link**: a direct QUIC connection between exactly two nodes (ALPN `dialtone/link/1`, `link.rs`), opened only while someone uses it. The allowlist decides who may open one, and iroh's hole punching finds a direct path; when two nodes cannot reach each other directly the link still runs through the relay and says so (`RELAY`, with more latency). - -```bash -# On the node with the camera: offer what arrives on 127.0.0.1:5000 as "cam". -dialtone link export cam --udp 127.0.0.1:5000 -ffmpeg -f dshow -i video="Cam Link 4K" -c:v libx264 -preset ultrafast -tune zerolatency \ - -g 30 -f mpegts "udp://127.0.0.1:5000?pkt_size=1128" # macOS: -f avfoundation -i "0" - -# On the viewer: deliver node "camera-node"'s "cam" to 127.0.0.1:6000 and play it. -dialtone link import camera-node/cam --udp 127.0.0.1:6000 -ffplay -fflags nobuffer -flags low_delay -framedrop udp://127.0.0.1:6000 - -dialtone link list # each link: DIRECT or RELAY, QUIC's Rtt, packets in / out / dropped -dialtone link close camera-node/cam -``` - -- **UDP** (`--udp`): on the exporting node, the address the source sends to; on the importing node, where packets are delivered. Packets travel as QUIC datagrams: unreliable and unordered, so a late frame is dropped instead of delaying the next one. A packet larger than the path allows is split into parts and put back together (a lost part drops its packet); `pkt_size=1128` (six MPEG-TS packets) keeps each one in a single datagram. Replies (RTCP) travel back to the source. -- **TCP** (`--tcp`): on the exporting node, a service to connect to (an RTSP or HTTP server); on the importing node, an address to listen on. Each TCP connection gets its own QUIC stream. -- Exports live in the running node until it restarts or `link close`; imports reconnect until closed. `GET /api/links` and `POST /api/links/{export,import,close}` are the API; the HUD lists this node's links with their path and Rtt. - -### Devices - -Every node lists the devices connected to it — cameras, microphones, speakers, keyboards, pointers (mice, trackpads), displays, printers, storage, Bluetooth devices and gamepads — using the OS's own view: `system_profiler` on macOS, `Get-PnpDevice` on Windows, `/sys` and `/proc` on Linux. Only each device's kind, name, bus (`built-in`, `usb`, `bluetooth`, `hid`, `display`, ...) and a short detail are kept; serial numbers and device IDs are dropped. - -```bash -./dialtone devices # table of this machine's devices -./dialtone devices --json # the same as JSON -curl -s http://127.0.0.1:8788/api/devices | jq -``` - -A running node lists its devices every 60 seconds. They are not gossiped: a peer asks for them when its HUD focuses the node (`GET /api/details?node_id=…`), and the HUD lists them under the node table; the tour's `DEV` step describes them. Device names (for example a Bluetooth headset named after its owner) are visible to every allowlisted node that asks. - ---- - -## 7. Supervised Processes - -### Keep a store Blob Running as a Daemon Process - -Once an executable binary or script is stored in the local store (`~/.dialtone/blobs`), you can configure `dialtone` to stage it into `~/.dialtone/run/-` (`chmod 0755`) and supervise it as a child process of the daemon: - -```bash -API_TOKEN=$(cat ~/.dialtone/api-token) - -# Spawn and supervise a store blob as a child process of dialtone -curl -X POST http://127.0.0.1:8788/api/processes/blob \ - -H "Authorization: Bearer $API_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "stats-blob-process", - "digest": "<64-hex-digest>", - "desired_state": "running", - "args": ["--interval", "5"], - "env": ["PROCESS_MODE=live"] - }' - -# Inspect live supervised processes (status, PID, restart_count, sha256) -curl -s http://127.0.0.1:8788/api/processes - -# Stop a supervised blob process cleanly -curl -X POST http://127.0.0.1:8788/api/processes/blob \ - -H "Authorization: Bearer $API_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "stats-blob-process", - "digest": "<64-hex-digest>", - "desired_state": "stopped" - }' - -# Remove it: stop it, forget its spec and delete its staged program -# (on the node that deployed it to the mesh, this removes every copy) -curl -X POST http://127.0.0.1:8788/api/processes \ - -H "Authorization: Bearer $API_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{"name": "stats-blob-process", "desired_state": "removed"}' -``` - -- **Crash Auto-Respawn**: Every second (and on process status queries), the daemon checks all managed child PIDs via `try_wait()`. If a process with `"desired_state": "running"` exits or crashes, `dialtone` increments `restart_count`, re-stages the verified store blob, and spawns a fresh child PID automatically. -- **Environment Sanitization**: the node's own `DIALTONE_*` / `DAEMON_V1_*` variables (such as `DIALTONE_SECRET`) are removed from every process's environment, and a spec's `env` entries with those prefixes are ignored. -- **Restart Persistence**: process definitions are saved to `~/.dialtone/config.json` and automatically re-staged and started when `dialtone` boots. - -## 8. HTTP API Quick Reference - -All `POST` routes require `Authorization: Bearer ` (or `X-Dialtone-Token: `) matching `~/.dialtone/api-token`. - -Requests are parsed with `httparse`. The API refuses what it never needs: `Transfer-Encoding` (501), missing, duplicate or conflicting `Content-Length` values and bodies shorter than declared (400), bodies over 2 MiB (413), and request heads over 64 KiB or with more than 64 headers (431). Query values are percent-decoded. - -| Method & Path | Description | -| :--- | :--- | -| `GET /` | The HUD (served with a per-response Content-Security-Policy nonce) | -| `GET /hud/...` | The HUD's static files (`app.js`, `style.css`, vendored three.js and h3-js) | -| `GET /health` | `{"status": "ok", "node": ..., "peers": ..., "boot_stages": ...}` | -| `GET /api/config` (`/api/boot-status`) | Boot stages, mesh config (`derived_keys` redacted), store path | -| `POST /api/mesh/join` | Join or switch the channel of the running node | -| `POST /api/daemon/install` | Install the daemon (OS login service) | -| `GET /api/state` | Full node state | -| `GET /api/mesh` | Every node's latest beat, the Rtt matrix and Services | -| `POST /api/blob` | Put a base64 blob in the store (`~/.dialtone/blobs`) | -| `GET /api/blob?digest=...` | Blob bytes and metadata (`HEAD` also supported) | -| `POST /api/blob/share` | Put a blob in the store and return its `iroh-blobs://ticket/...` | -| `POST /api/blob/pull` | Pull a blob by ticket over QUIC into the store | -| `GET /api/processes` | Supervised processes with live PID / status | -| `GET /api/devices` | Devices connected to this node (cameras, microphones, keyboards, ...) | -| `POST /api/processes/blob` | Stage a program blob (or ticket) and run / stop it as a process; `"deploy_to_mesh": true` announces it to the mesh (`"deploy_targets"` to name nodes) | -| `POST /api/processes` | Same, and `{"name": ..., "desired_state": "removed"}` stops a process and forgets it (mesh-deployed copies follow) | -| `POST /api/probe` | Run one probe now, `{"all": true}` for a full probe (`GET` returns the latest); nodes check the mesh every 30s | -| `POST /api/restart` | Exit so the node's service starts it again on the binary now at its path (`dialtone join ` uses it to replace a running node on Windows) | -| `GET /api/net` | Traffic since boot: socket bytes in and out, connections, gossip messages, neighbors, iroh-gossip data and control frames, and peer scores | -| `GET /api/details?node_id=…` | A node's devices and full probe report, fetched from that node (kept 10s) | - - ---- - -## 9. Environment Variables & Local Paths - -| Variable / Path | Default | Purpose | -| :--- | :--- | :--- | -| `DIALTONE_STATE_DIR` / `DIALTONE_HOME` | `~/.dialtone` | Root state directory for config, identity, blobs, and staged executables | -| `DIALTONE_IROH_SECRET_KEY_FILE` | `~/.dialtone/iroh-secret-key` | Persistent 32-byte Ed25519 Iroh endpoint secret key (`0600` permissions) | -| `DIALTONE_API_TOKEN` | `~/.dialtone/api-token` | Bearer token required for all `POST` control API routes (and required when `--listen` is non-loopback) | -| `DIALTONE_HUD_DIR` | *(unset)* | Serve the HUD from this directory (e.g. `src/hud`) instead of the copy in the binary, uncached: HUD edits show on a browser reload with no rebuild or restart | -| `DIALTONE_CHANNEL` | `dialtone` | Default gossip channel name when `--channel` is not passed | -| `DIALTONE_SECRET` (`DIALTONE_SECRET_KEY`) | *(unset)* | Channel secret used to derive Argon2id `v2` channel keys on boot | -| `~/.dialtone/config.json` | — | Host-local mesh config (`0600`): Argon2id `derived_keys` (no plaintext secret), `seeds`, `allowlist`, `used_invite_nonces`, and supervised process specs | -| `~/.dialtone/api-token` | — | Auto-generated 256-bit local HTTP control API bearer token (`0600`) | -| `~/.dialtone/blobs/` | — | Blob store (iroh-blobs `FsStore`; blobs named by `sha256/` tags) | -| `~/.dialtone/run/` | — | Staged `0755` executables spawned by the blob process supervisor | -| `DIALTONE_AUTO_UPDATE` | *(on)* | `0` stops a node updating itself to new releases | -| `DIALTONE_RELEASE_URL` | GitHub releases | Where a node looks for releases (a mirror); they must still be signed with the release key | -| `DIALTONE_UPDATE_CHECK_SECS` | `3600` | How often a node asks for the latest release | -| `~/.dialtone/update.json` | — | Self-update state: the release on trial, the one kept, versions rolled back | -| `~/.dialtone/bin/dialtone.prev` | — | The binary that ran before the last update (what a rollback restores) | - ---- - -## 10. Working on dialtone: `./dialtone.sh` - -Rust and cargo do everything: the dev tasks are a small crate, `xtask/`, and `./dialtone.sh ` is the one entry point (a one-line wrapper for `cargo run -p xtask`). Nothing else is needed on the machine (no Python, jq or curl); `test`, `dev` and `deploy` reach the test VMs with the system's `ssh` / `scp`, and `git` runs the leak gate. Only the `dialtone` binary is distributed and run. - -`cargo test` covers each capability with real iroh endpoints (signed gossip between two nodes, blob pulls through the node's downloader, the handshake allowlist, a two-node probe, the supervisor and the API), and runs real nodes from the built binary on every OS: `tests/node.rs` (one node: CLI, secrets, allowlist, API auth, supervisor, blobs, probe, one-shot runs) and `tests/e2e.rs` (three nodes: mesh, gossip only in steady state, probes, mesh deploys, a direct link, a stopped node caught, an open channel joined by invite, a node that started while its seed was down, a seed that restarted) and `tests/update.rs` (self-update from a signed release: a healthy one kept, one that panics or never gets healthy rolled back, a node updated from a peer, a node with no service restarting itself; not on macOS, where the test releases would be unsigned). - -**All testing goes through one command, `./dialtone.sh test`.** With no options it runs every test end to end on Linux VMs, never on the machine you type on: that machine only lints, packs the sources and drives the VMs over SSH. Options pick one part, or run on this machine instead (GitHub CI runs `test --here`). - -```bash -./dialtone.sh test # everything: lint here; on the build VM the whole cargo test - # suite and the release build; the rejoin test; every VM - # installs that build and must pass its gossip probe on exactly - # that binary, then a full probe; then 10 scale nodes per VM - # as one mesh -./dialtone.sh test --scale 20 # ... with 20 scale nodes per VM (--scale 0 skips them) -./dialtone.sh test --only lint # leak gate (no host names / NodeIds in git), domain language, - # fmt and clippy -./dialtone.sh test --only suite # just cargo test, on the build VM -./dialtone.sh test --only suite -- --test e2e # just the three-node tests (anything after -- goes - # to cargo test) -./dialtone.sh test --only rejoin # a node on the previous signed release joins the live channel - # by invite, goes away, rejoins and must update itself to the - # newest release, having heard of it in a peer's beat -./dialtone.sh test --only scale --scale 20 --secs 60 # just the scale test on the VMs' installed - # build: convergence time and traffic per node per VM -./dialtone.sh test --only probes # every VM's latest probe in the live mesh; fails unless all pass -./dialtone.sh test --here # on this machine instead: lint, cargo test, release build -./dialtone.sh test --here --only scale --scale 30 # 30 nodes on this machine; fails above - # SCALE_BUDGET_KBPS kbit/s in or out per node when set -``` - -Two more tasks look after the VMs; neither tests anything: - -```bash -./dialtone.sh dev # set up every VM for development: C toolchain, pkg-config, git, curl (apt) - # and Rust (rustup) with rustfmt and clippy; skips what is already there -./dialtone.sh dev user@10.0.0.9 # ... or any machine you can SSH to -./dialtone.sh deploy # build on the build VM and install on every VM, waiting for every probe - # (`test` already deploys the build it tested) -./dialtone.sh deploy --tag v0.5.1 # every VM downloads that release instead (SHA-256 checked) -``` - -The VMs come from `fleet.local.env` next to the script. It is never committed (`*.local.env` is ignored), so host names and addresses stay on your machine. Each VM runs a node as the systemd user service `dialtone` (`dialtone daemon install`); the build VM keeps its cargo target directory between runs, so only what changed is rebuilt, and every other VM gets the build VM's binary (so all VMs share its OS and architecture). - -```bash -FLEET_NODES="vm-alpha vm-beta vm-gamma" # every VM; deploy waits for all of their probes -BUILD_NODE="vm-alpha" # builds and runs the test suite (default: the first) -SSH_vm_alpha="-i $HOME/.ssh/id_vm user@203.0.113.10" # SSH options and destination -SSH_vm_beta="user@203.0.113.11|-J vm-alpha user@10.0.0.2" # alternatives; the first that answers wins -SSH_vm_gamma="user@203.0.113.12" -``` +`up` starts an unmanaged foreground node and prints its HUD URL (normally http://127.0.0.1:8788); this `.local/bin` copy does not self-update. To join an existing channel, obtain an invite from a member and follow the [join instructions](docs/guide.md#3-join-other-computers-with-an-invite). Joining with an invite or running `daemon install` explicitly installs and starts the managed `~/.dialtone/bin` copy, which can receive signed updates; the installer does neither. -To check a single running node by hand, `./dialtone probe --all` runs every probe check on it: mesh, neighbors, beats, store, pulls from peers, programs and security. +| Supported platform | v0.5.3 binary | +| --- | --- | +| Linux x86_64 | Static musl | +| Linux ARM64 | GNU/glibc; not an Alpine/musl binary | +| macOS Apple Silicon | Native ARM64 (including Rosetta shells) | +| Windows x86_64 | Native x64 | -**Releasing.** Bump `version` in `Cargo.toml`, commit, and push a tag `vX.Y.Z`. The release workflow builds every binary with `./dialtone.sh release build ` (the same command builds one here), then `./dialtone.sh release manifest` signs `dialtone-release.json` with the `DIALTONE_RELEASE_KEY` repository secret (it refuses a key whose public half is not the one in `src/update.rs`). Running nodes pick the release up within the hour, or within a beat once any peer runs it. +Intel macOS, Windows ARM64, and 32-bit systems have no published binary in this release; the installers refuse them. See [requirements and source builds](docs/install.md#supported-platforms). -**Build profiles.** `cargo build --release` is the everyday optimized build (no LTO, parallel and incremental codegen): `./dialtone.sh`, GitHub CI and deploys use it, and a one-file change rebuilds in about a second. Published binaries are built with `cargo build --profile dist` (size-optimized, fat LTO), which takes about a minute and only runs when a version is tagged. +[Download and inspect before running](docs/install.md#download-and-inspect) · [Version, directory, and manual download options](docs/install.md) · [Full user guide](docs/guide.md) · [Releases](https://github.com/timcash/dialtone/releases) · [Design and domain language](goal.md) diff --git a/docs/guide.md b/docs/guide.md new file mode 100644 index 0000000..f71a16f --- /dev/null +++ b/docs/guide.md @@ -0,0 +1,637 @@ +# Dialtone User Guide + +`dialtone` is a single-binary Rust + **Iroh 1.3** peer-to-peer mesh control plane, 3D tactical HUD & terminal `top` monitor, content-addressed blob store (`iroh-blobs`), and process supervisor. It runs without SSH, Git, or Tailscale/VPN runtime dependencies. + +This guide uses the project's [domain language](../goal.md#domain-language): one word per concept (Node, NodeId, Peer, Mesh, Channel, Secret, Allowlist, Invite, Seed, Message, Beat, Inventory, Stats, Blob, Digest, Store, Ticket, Program, Process, Probe, HUD, API). + +```text +$ dialtone --help +usage: dialtone [action] [flags] + +Single-binary Iroh 1.3 + Rust mesh control plane, 3D tactical HUD, blob store & daemon. +Running `dialtone` with no arguments boots in dependency order and prints the local Web HUD URL. + +actions: + up Start the node: HUD -> store -> Iroh QUIC -> mesh + join Join a channel with an invite from any member (dialtone-invite-v2:...), + install this binary and start the node at login (--once: only join) + join Unlock (or start) a channel with its secret + secret Generate a new channel secret (dt-...) + allowlist [list|add|remove] [] Manage the allowlist in ~/.dialtone/config.json + blob [share|pull] Share a file or text as a blob, or pull a blob by ticket + link export --udp|--tcp Offer a local source to peers over a direct link + link import / --udp|--tcp Open a peer's source and deliver it here + link [list|close ] Show links (path direct or relay, Rtt, packets), or close one + invite [--ttl 24h] Make an invite any node can join with until it expires (max 30d) + daemon [install|status] install: put this binary in ~/.dialtone/bin, register the login + service and start the node (a running one restarts into it) + probe [--all] Run one probe now: the gossip checks (MSH, NBR, BEAT; nodes run them + every 30s), and with --all the store, pulls, programs and security + (STO, PUL, PRC, SEC) + devices [--json] List the devices connected to this machine (cameras, mics, keyboards, ...) + status Print this node's NodeId and transport report + help Show this help + +flags: + --node Node name (default: saved config or hostname) + --listen HUD and API listen address (default: 127.0.0.1:8788) + --api-token Explicit API bearer token for POST routes (default: ~/.dialtone/api-token) + --channel Channel name (default: dialtone) + --secret Channel secret (or set DIALTONE_SECRET) + --ttl TTL for 'dialtone invite' (e.g. 15m, 1h, 7d; default: 24h) + --addr Direct address for 'dialtone allowlist add' (repeatable) + --force Pull over QUIC even if the blob is already in the store + --udp 'dialtone link': where the source sends (export) or packets go (import) + --tcp 'dialtone link': the service to connect to (export) or listen on (import) + --json Print JSON ('devices', 'invite', 'link list') + --once 'up': boot, beat once and exit; 'join': only join, start nothing + --all 'dialtone probe': also test the store, pulls, programs and security + +transport (the default: relays on, no public DNS or DHT, Tailscale addresses left out): + --private-mesh No relays: dial peers only at their direct addresses + --relay-only Advertise only the relay, no direct addresses + --relay-url Use this Iroh relay instead of the public ones (repeatable) + --quic-port Bind the QUIC endpoint to this UDP port + --lan Also find peers on the local network (mDNS) + --allow-tailnet Also use Tailscale addresses +``` + +HUD keys (at http://127.0.0.1:8788): + +```text + Up / Down Arrow Zoom camera in/out across Layers 1..5 (GLOBE -> PROCESS) + Left / Right Arrow Step backward/forward through the 5-step tour (MSH BLB PRC NET DEV) and nodes + Double-Click Node / Row Zoom into focused node symbol (resets to L1 GLOBE after L5) + Click [1 MSH] .. [5 DEV] in Bottom CC Jump directly to any capability step in the live Closed Captions +``` + +--- + +## Quick Start (60 Seconds) + +### 1. Install the Single Binary + +Use the [verified installer](install.md), or [build from source](install.md#build-from-source). Run the following commands from the installed binary directory, or replace `./dialtone` with `dialtone` after adding it to PATH. + +### 2. Boot a Node & Open the 3D Tactical HUD + +```bash +./dialtone up --node node-alpha +``` + +Open **`http://127.0.0.1:8788`** in your browser to view the live 3D mesh topology and terminal `top` stats table. + +### 3. Join Other Computers with an Invite + +On the first node, start a channel and make an invite (valid 24h by default, up to `--ttl 30d`): + +```bash +./dialtone join "$(./dialtone secret)" --node node-alpha --once # a new channel (keep the secret if you want it) +./dialtone up --node node-alpha # leave it running +./dialtone invite --ttl 7d # prints dialtone-invite-v2:... +``` + +Any other computer joins with the invite alone: [install the binary](install.md), then explicitly join: + +```bash +./dialtone join 'dialtone-invite-v2:...' +``` + +On Windows, use `.\dialtone.exe join 'dialtone-invite-v2:...'`. + +`dialtone join ` joins the channel, copies itself to `~/.dialtone/bin`, installs the node as a login service (launchd, systemd `--user`, or a Windows logon task) and starts it, so the downloaded file can be deleted. Where no login service can run (a container without systemd, say) the node starts now and keeps itself running: it restarts after updates and crashes, but not after a reboot. Run it again with a newer binary and the running node restarts into it. Options: `--node ` (default: the hostname), `--listen `. With `DIALTONE_STATE_DIR` set (a second node on one machine, or a trial) everything stays in that folder and the node starts now but not at login. Each release also has a `.sha256` next to every binary, and once installed a node only ever updates to binaries the release key signed. `dialtone join --once` only records the channel. + +### 4. Optional: Install as a Background Login Service & Check the Mesh + +```bash +# Install this binary as a user-level OS service (launchd / systemd --user / Windows logon task) and start it +./dialtone daemon install + +# Check the running node: mesh, beats, store, pulls from peers, programs and security +./dialtone probe --all +``` + +--- + +## 1. Installation & Boot Pipeline + +### Pre-Compiled Release Assets + +Every GitHub Release publishes standalone, size-optimized single-file executables with all runtime assets and the Web UI compiled directly into the binary: + +| Platform | Release Asset | +| :--- | :--- | +| **macOS (Apple Silicon)** | `dialtone-macos-arm64` | +| **Linux (x86_64, static musl)** | `dialtone-linux-x86_64` | +| **Linux (ARM64, GNU/glibc)** | `dialtone-linux-arm64` | +| **Windows (x86_64)** | `dialtone-windows-x86_64.exe` | + +### 5-Stage Boot Sequence + +Running `./dialtone` (with no arguments, or `./dialtone up`) boots 5 subsystems in strict dependency order and starts the local Web HUD immediately: + +```text +[BOOT 1/5] Local Runtime & Stdout Logger ................. [READY] (node=node-alpha, os=macos/aarch64) +[BOOT 2/5] Local Web HUD & Config Server ................. [READY] http://127.0.0.1:8788 +[BOOT 3/5] Content-Addressed Blob Store (iroh-blobs) ..... [READY] ~/.dialtone/blobs +[BOOT 4/5] Iroh 1.3 QUIC Endpoint (No-Tailnet NIC) ....... [READY] id=a67ff536b0f9.. ip=192.168.1.40 +[BOOT 5/5] Gossip Mesh & Channel Secret ................ [READY] channel=ch-7981c39da07e peers=2 +``` + +- **Port Auto-Fallback**: Defaults to `127.0.0.1:8788` (override with `--listen `). If `8788` is in use and `--listen` was not explicitly forced, `dialtone` automatically scans `127.0.0.1:8788..=8799` (falling back to an OS-assigned port). +- **One-shot run**: `./dialtone up --once` boots, prints one beat and exits. Next to a running node it uses a private store and leaves the config alone. + +--- + +## 2. Local Web HUD, Terminal `top` UI & Stats + +Open **`http://127.0.0.1:8788`** to access the embedded tactical HUD: + +- **Terminal `top` table**: mesh-wide rows (`MSH`, `NET`, `PRB`, `CPU`, `MEM`, `DSK`), where `PRB` counts each probe check passing across nodes (`MSH` `NBR` `BEAT` `PUL` `PRC`), then one row per node (`NODE`, `ARCH`, `CPU`, `MEM`, `DSK`, `IP/PATH`, `RX/TX`, `LNK`, `RTT`, `JIT`, `PROC`, `PRB`), then the focused node's devices. +- **Threshold colours**: values stay greyscale when nominal, turn amber at the warning level and red at the error level (CPU 75% / 92%, memory 78% / 92%, disk 82% / 94%). +- **Tour**: visits every node and steps through `MSH` (mesh), `BLB` (store and blob pulls), `PRC` (probe program), `NET` (beats and Rtt) and `DEV` (devices); the closed captions narrate that node's latest probe. +- **Interactive 3D Mesh Topology**: Drag to orbit, scroll to zoom, or click any peer node to inspect its live QUIC links and metadata. +- **Menu** (bottom-right button): tour and camera controls, zoom layers, display toggles, and — under + *05 // Mesh setup (CLI)* — the commands for creating a mesh, inviting and allowing nodes. The page holds no API + token, so mesh changes are made with the CLI. +- **Endpoints the HUD uses**: `GET /` (the page), `GET /hud/...` (its static files) and `GET /api/mesh` (polled + every 1.5s). + +--- + +## 3. Starting a Gossip Mesh from Scratch + +Because `dialtone` ships with **zero hardcoded mesh peers** and enforces a **deny-by-default peer allowlist** + **Argon2id / XChaCha20-Poly1305 encrypted channel**, a brand-new node boots into an isolated `dialtone:locked-standby` topic until you configure a channel secret and authorize your peers. + +Below are the two ways to seed a new multi-node mesh from scratch (using generic example nodes `node-alpha` and `node-beta`). + +### Option A: An Open Channel with Invites (Simplest) + +A channel whose nodes have an **empty allowlist** is open: any node holding the channel keys is a member, and nobody lists anybody's NodeId. Members hand the keys out for **invites**. + +1. On `node-alpha`, start the channel and the node, then make an invite: + + ```bash + ./dialtone join "$(./dialtone secret)" --node node-alpha --once + ./dialtone up --node node-alpha + ./dialtone invite --ttl 24h + ``` + +2. On any other host, join with the invite (or use the install script above): + + ```bash + ./dialtone join "dialtone-invite-v2:..." --node node-beta + ``` + +**How an invite works.** `dialtone invite` asks the running node for one (`POST /api/invites`). It names the channel, an expiry and up to four members to present it to (that node, then its seeds; each with its NodeId, home relay and direct addresses), under a MAC with the channel's `auth_key`; it carries **no keys**. `dialtone join ` opens one QUIC stream to the first named member that answers (ALPN `dialtone/join/1`) and presents it; the member checks the MAC and the expiry and answers with the channel keys and the same list of seeds. So an invite works while any one of its members is up. The QUIC handshake proves the answer comes from the NodeId the invite names. The joining node saves the keys (`config.json`, `0600`), clears any allowlist and starts. + +- An invite works for any number of nodes until it expires, then for none. Make a new one with `dialtone invite`. +- The node that made the invite must be online when someone joins with it. +- Once joined, a node keeps the keys. To remove members, start a new channel (a new secret) and invite the nodes that should stay. +- A channel with an allowlist refuses invites; its nodes keep authorizing each other by NodeId (Option B). + +--- + +### Option B: Explicit Allowlist Provisioning Across N Nodes (Deterministic / Automated) + +If you are provisioning 2, 3, or more hosts via a setup script or SSH, you can pre-populate each node's allowlist directly using `dialtone status`, `dialtone join --once`, and `dialtone allowlist add`: + +```bash +# 1. On EVERY host, initialize its persistent Ed25519 identity (~/.dialtone/iroh-secret-key) +# and record its 64-character hex "node_id": +./dialtone status --node + +# 2. On ONE host, generate the shared channel secret: +./dialtone secret +# -> e.g. dt-R9xK4mP7vQ2wL8nJ5tB3yF6hC1zX0sW9_AbCdEfGhIj + +# 3. On EVERY host, derive the Argon2id channel keys into ~/.dialtone/config.json: +./dialtone join "" --node --once + +# 4. On EVERY host, authorize every peer's NodeId (adds to allowlist & seeds): +./dialtone allowlist add +./dialtone allowlist add +./dialtone allowlist add + +# Verify the local allowlist and seeds: +./dialtone allowlist list + +# 5. Start dialtone in the foreground (or install as a persistent background service): +./dialtone up --node +# or: +./dialtone daemon install +``` + +### Step 4 — Verify Mesh Convergence + +Within a few seconds of starting, verify that all nodes are exchanging encrypted messages (`dialtone.iroh.envelope.v5`) and incrementing their beat `counter`. All nodes must run the same envelope version, so upgrade a mesh together: + +```bash +# Check discovered peers and beat counters via the local HTTP API +curl -s http://127.0.0.1:8788/api/state | jq '.nodes[] | {node, role, node_id, counter}' + +# Check the 5 boot stages and active channel fingerprint (ch-...) +curl -s http://127.0.0.1:8788/api/config | jq '{node, channel_fingerprint: .mesh_config.channel_fingerprint, boot_stages}' +``` + +Or open **`http://127.0.0.1:8788`** in your browser to view the live 3D topology and terminal `top` table. + +--- + +## 4. Channel Security, Peer Allowlist & Control API Reference + +**How the mesh is protected** + +- **Open channel or allowlist, at the handshake.** With an empty allowlist the channel is open: gossip and join (`dialtone/join/1`) accept any NodeId, gossip frames that do not open with the channel keys are dropped (and cost their sender its score), and fetch, blobs and link accept only members, NodeIds this node has had a valid message from. With NodeIds listed, every QUIC connection (gossip and blobs, in and out) is closed right after the TLS handshake unless the remote NodeId is on the allowlist. `dialtone allowlist add/remove` edits `~/.dialtone/config.json`; a running node picks the change up within 5 seconds, no restart. +- **Signed messages.** Nodes gossip three typed messages (see [Scaling the mesh](#scaling-the-mesh)): a **Beat** (liveness, load, the node's probe checks and its gossip neighbors with their Rtt), an **Inventory** (the node's processes, services and details) when it changes, and a **Deploy** (a program the node deploys to the mesh, or removes from it). Each message is signed with the sender's Key and encrypted with the channel keys. A node drops messages whose signature does not match the NodeId they claim, messages from NodeIds not on its allowlist (when it has one), and replays (each node's `sent_unix_ms` must increase and be within 5 minutes of local time — keep node clocks roughly in sync). +- **No process secrets on the wire.** An inventory lists each process without its `env` or `args`. +- **Deploys are announced, and only targeted nodes pull.** `POST /api/processes/blob` with `"deploy_to_mesh": true` (and optionally `"deploy_targets": ["node-name", "", ...]`) makes the origin gossip a signed **Deploy** naming the program, its blob ticket and its targets (every node when none are named). A targeted node pulls the program, from up to three peers whose inventories say they already run it (gossip neighbors first) and then from the origin, after a random delay of up to one beat interval so a large mesh does not pull at once; it checks the SHA-256, stages and starts it. Nothing auto-deploys from inventories, and no node's probe program is ever deployed. +- **Deploys follow their origin.** A copy is never announced further. It is removed when the origin announces the program removed (removing it on the origin), no longer targets this node, or stops announcing it for 30 minutes while still in the mesh. The origin announces every change at once, and all its deploys again every 10 minutes and soon after a node joins (removed ones for an hour), so a node that was away catches up through gossip alone. +- **Deploys only from the allowlist.** A Deploy is admitted only from an allowlisted signer, and blob pulls use the node's own endpoint, so each provider's allowlist decides. +- **HUD.** The page carries no API token; a per-response Content-Security-Policy nonce lets only its own scripts run. three.js and h3-js are compiled into the binary and served from `/hud/vendor/`, so the HUD loads nothing from the Internet. + +### Unlock & Join the `"dialtone"` Channel (`join` & `secret`) + +The `"dialtone"` channel (and any custom `--channel `) is **secret-protected and end-to-end encrypted**: +- Booting `dialtone` without a configured secret places the node on an isolated per-node standby topic (`dialtone:locked-standby`) and does **not** dial mesh seeds until unlocked. +- **Minimum Secret Strength**: Secrets must be at least 16 characters long with multiple character classes and `>= 8` unique characters; weak or dictionary secrets (`"dialtone"`, `"dialtone2"`, `"secret123"`, `"default"`) are rejected. Run `./dialtone secret` to generate a CSPRNG 256-bit secret (`dt-...`). +- **Argon2id Key Derivation (`v2`) & XChaCha20-Poly1305 Gossip Encryption**: + 1. `dialtone` derives three domain-separated 32-byte subkeys (`topic_id`, `auth_key`, `enc_key`) from `(channel, secret)` using **Argon2id** (`m=19456 KiB, t=2, p=1`). + 2. Only the derived subkey bundle (`derived_keys`) is persisted in `~/.dialtone/config.json` (`0600` permissions) — the plaintext secret is **never** written to disk. Any legacy `~/.dialtone2/config.json` is automatically migrated and scrubbed on startup. + 3. Every message broadcast over `iroh-gossip` is signed with the sender's Key and encrypted with `enc_key` using **XChaCha20-Poly1305** (`dialtone.iroh.envelope.v5`: a binary frame, random 24-byte nonce). Unencrypted or unsigned frames are dropped. +- **Deny-by-Default Peer Allowlist (`allowlist`)**: + - On the main `"dialtone"` channel, inbound peers are **denied by default** unless their `NodeId` is listed in the host's local `~/.dialtone/config.json` (`allowlist`), even if `--invite` is passed. + - Manage the allowlist via CLI: + ```bash + ./dialtone allowlist list + ./dialtone allowlist add + ./dialtone allowlist add --addr 192.168.1.50:19440 + ./dialtone allowlist remove + ``` +- **Expiring invites (`invite`)**: + - The running node makes an invite (`dialtone-invite-v2:...`) that any node can join with until it expires: + ```bash + ./dialtone invite --ttl 15m + ``` + +```bash +# Generate a high-entropy 256-bit channel secret +./dialtone secret + +# Unlock the default 'dialtone' channel with a secret (updates a running local daemon live, or boots a new one) +./dialtone join + +# Redeem a single-use invite while joining +./dialtone join --invite dialtone-invite-v1: + +# Save derived channel keys to ~/.dialtone/config.json (0600 permissions) and exit immediately +./dialtone join --once +``` + +### Local HTTP Control API Bearer Authentication (`~/.dialtone/api-token`) + +All state-changing `POST` routes on the local HTTP control plane require bearer token authentication (`Authorization: Bearer ` or `X-Dialtone-Token: `): +- On first boot, `dialtone` generates a 32-byte random token in `~/.dialtone/api-token` (`0600` permissions). Override with `--api-token ` or `DIALTONE_API_TOKEN`. +- Binding `--listen` to a non-loopback address (e.g. `0.0.0.0:8788`) is refused unless an explicit `--api-token` or `DIALTONE_API_TOKEN` is configured. +- The HTTP server processes requests concurrently on bounded process threads (`MAX_CONCURRENT_HTTP_CONNECTIONS = 32`) with a 2-second socket read/write timeout and 2 MiB body size limit. + +```bash +API_TOKEN=$(cat ~/.dialtone/api-token) +curl -X POST http://127.0.0.1:8788/api/mesh/join \ + -H "Authorization: Bearer $API_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"channel":"dialtone","secret":"dt-...","node":"node-alpha"}' +``` + +### Transport Inspection (`status`) + +```bash +# Bind persistent Ed25519 identity (~/.dialtone/iroh-secret-key) and print transport diagnostics +./dialtone status --node node-alpha +``` + +### Transport & Discovery Flags + +A node never publishes itself to a public directory (Pkarr DNS or Mainline DHT), so its `NodeId` and IP addresses never appear there; the full probe's `SEC` check fails if it ever does. By default it uses the public Iroh relays and leaves Tailscale addresses (`100.64.0.0/10`, `fd7a:115c:a1e0::/48`) out of what it advertises, binding QUIC to the primary physical IPv4 interface. + +| Flag | Behavior | +| :--- | :--- | +| `--private-mesh` | No relays: peers are dialed only at the direct `ip:port` addresses from `allowlist add --addr` or invites. | +| `--relay-only` | Strips direct IP addresses from tickets so traffic goes only through the relay (`relay_only` profile). | +| `--relay-url ` | Uses this Iroh relay instead of the public ones (repeatable). | +| `--quic-port ` | Binds the Iroh QUIC UDP socket to a fixed port (e.g. `19440`) so peers can dial it directly. | +| `--lan` | Also finds peers on the local network with mDNS (`lan_only` profile). | +| `--allow-tailnet` | Also advertises Tailscale interface addresses. | + +--- + +## 5. Persistent OS Daemon & Service Units + +`dialtone` can install itself into your user account so it starts automatically on boot/login without requiring `root` or `sudo`. Derived Argon2id channel keys are saved to `~/.dialtone/config.json` (`0600`) and raw secrets are never written to disk or passed on the service command line: + +```bash +# Copy binary to ~/.dialtone/bin/ and register OS login service +./dialtone daemon install + +# Check installation status and saved configuration +./dialtone daemon status +``` + +| Operating System | Installed Service Blob | +| :--- | :--- | +| **macOS** | `~/Library/LaunchAgents/com.timcash.dialtone.plist` (`launchctl load -w`) | +| **Linux** | `~/.config/systemd/user/dialtone.service` (`systemctl --user enable --now dialtone.service`) | +| **Windows** | `~/.dialtone/start-dialtone.cmd` registered in `HKCU\...\Run\DialtoneDaemon` + Scheduled Task `DialtoneDaemon` | + +### Self-update: a new release reaches every node on its own + +A node that runs from `~/.dialtone/bin` (every service install does) updates itself whenever a new release is tagged, and rolls back a release that does not start healthy: + +- **Detect.** Every beat carries the version its node runs. A node asks GitHub for the latest release about once an hour, and as soon as a peer's beat shows a newer one. +- **Trust.** The release workflow signs `dialtone-release.json` (each binary's SHA-256, BLAKE3 hash and size) with the release key, and every binary holds the public key. A binary is installed only if the manifest verifies and the binary matches it, so a binary from a peer is as trusted as one from GitHub. +- **Fetch.** From peers that already run the release on the same OS and architecture (iroh-blobs), else from GitHub. A node that cannot reach GitHub still updates from its peers. +- **A/B install.** The running binary moves aside as `dialtone.prev`, the new one takes its path, and the node exits (code 75) so its service starts the new one. A node with no service (one `dialtone join` could not install, or a bare `nohup dialtone up &`) runs as its own restart loop: it starts the new binary itself, and restarts the node after a crash (2s, doubling to 60s). +- **Trial and rollback.** The new binary is kept once it has run for a minute with gossip joined and, if the old one had neighbors, at least one neighbor. If it is not healthy within 3 minutes, or it fails to start 3 times, `dialtone.prev` takes the path back, the version is marked bad in `~/.dialtone/update.json` (never tried again), and the old binary runs. + +`DIALTONE_AUTO_UPDATE=0` turns it off. A binary run from anywhere else (a development build) never replaces itself. `./dialtone.sh test --only probes` shows the version every test VM runs. `./dialtone.sh test --only rejoin` checks the whole path on the live channel: a node on the previous signed release joins by invite, goes away and rejoins, hears of the newest release in a peer's beat, installs it, restarts and keeps it (about two minutes on the test VMs). + +--- + +## 6. Blob Store + +The store is an iroh-blobs `FsStore` in `~/.dialtone/blobs/` (`blobs.db`, `data/`). Every blob is named by its digest through the tag `sha256/`, which points at its BLAKE3 hash; tagged blobs are kept and garbage collection removes anything untagged (such as an interrupted download). Uploads are checked against their SHA-256 before they are added, and a pulled blob is checked against the ticket's digest before it is tagged. Blobs left in the old one-file-per-digest layout are imported the first time the node starts. A store belongs to one process: one-shot runs (`--once`) next to a running node use a private temporary store. + +### Store, Fetch & Verify Blobs via HTTP + +```bash +API_TOKEN=$(cat ~/.dialtone/api-token) + +# 1. Upload base64 payload into the verified store +BLOB_B64=$(printf '#!/bin/sh\nsleep 30\n' | base64 | tr -d '\n') +curl -X POST http://127.0.0.1:8788/api/blob \ + -H "Authorization: Bearer $API_TOKEN" \ + -H "Content-Type: application/json" \ + -d "{\"bytes_base64\":\"$BLOB_B64\"}" + +# 2. Check blob presence and byte length (HEAD) or download bytes/metadata (GET) +curl -I "http://127.0.0.1:8788/api/blob?sha256=<64-hex-digest>" +curl -s "http://127.0.0.1:8788/api/blob?sha256=<64-hex-digest>" +``` + +### Live Cross-Peer `iroh-blobs` QUIC Share & Pull (`blob share` / `blob pull`) + +Every running `dialtone` daemon attaches `iroh_blobs::BlobsProtocol` to its live QUIC router so peers can share and pull content-addressed blobs directly over QUIC: + +```bash +# On Node A: add a file (or text) to the store and get a ticket for it +./dialtone blob share ./process-script.sh +# -> {"digest": "sha256:...", "ticket_uri": "iroh-blobs://ticket/blob...#sha256:...", ...} + +# On Node B: pull it over QUIC from Node A; its SHA-256 is checked against the ticket before it is kept +./dialtone blob pull "iroh-blobs://ticket/blob...#sha256:..." --force +``` + +--- + +### Self-test loop (Probe) + +Every running node checks the gossip mesh every 30 seconds. These checks read what gossip already brought, so they cost no traffic of their own: + +| Check | What it proves | +| :--- | :--- | +| `MSH` | Every allowlisted peer is in the mesh | +| `NBR` | The node has at least two gossip neighbors (one in a two-node mesh) | +| `BEAT` | Every peer's beats are fresh (within three of its beat intervals) and every peer hears as many nodes as this one | + +A full probe also tests the node's other capabilities, which move data, so it runs only when asked (`dialtone probe --all`, or `POST /api/probe` with `{"all": true}`; `./dialtone.sh test` and `deploy` run one on every test VM): + +| Check | What it proves | +| :--- | :--- | +| `STO` | A fresh blob is written to the store and read back intact | +| `PUL` | Up to 3 peers, chosen at random, each write a fresh blob on request; it downloads over QUIC through the node's downloader, SHA-256 verified | +| `PRC` | The probe program, staged from the store, is running under the supervisor | + +A compact report (the checks, without per-peer results) travels in the node's beats, so each HUD shows every node's results (PRB row, tour steps). Failed checks are logged. Probe blobs are forgotten after use, so the store does not grow. `dialtone probe` (or `POST /api/probe`) runs one immediately; `GET /api/probe` returns the latest. + +### Scaling the mesh + +Gossip is routed the way [libp2p GossipSub](https://docs.libp2p.io/concepts/pubsub/overview/) routes it, on top of iroh-gossip's HyParView membership and Plumtree broadcast tree: + +- **A few neighbors, not every node.** Each node keeps 2 to 5 gossip neighbors. Below two (GossipSub's `D_lo`) it joins up to three known peers chosen at random; nobody dials every other node. A message reaches the whole mesh along the broadcast tree, each node forwarding it once. +- **Gossip only.** Once a node has joined, it talks to the mesh only through gossip: no node fetches from another unless someone asks (a HUD focusing a node, a full probe). The three-node test (`tests/e2e.rs`) checks that no node opens a connection in 20s of steady state. +- **Small, fixed-size beats.** A beat is a compact binary record (postcard, `wire.rs`), about 255 bytes sealed for a healthy node and at most about 310: name, counter, load (CPU, memory, disk, network), coarse location, home relay and two addresses, the probe's checks, the inventory version and up to five gossip neighbors with their Rtt. No seed lists, no per-peer results, nothing that grows with the mesh. Rolling summaries are not gossiped. +- **Rtt for free.** Each neighbor's Rtt is QUIC's own estimate on the gossip connection that is already open, read through a weak handle the allowlist hook keeps (the Paths actor); no ping is sent. So is whether the path is direct or through the relay. +- **Separate topics.** Beats go on the channel's beats topic; inventories are broadcast on its events topic when they change. An inventory leaves out process pids, statuses and restart counts, so a restart does not re-broadcast it. +- **Beat interval from a budget.** Every node hears every beat, so a node beats every `clamp(nodes × 500 B / 4 KB/s, 5, 120)` seconds: about 4 KB/s of incoming beats per node at any size (5s up to 40 nodes, 13s at 100, 120s at 1,000). Freshness checks use each peer's own interval (three of them). iroh-gossip remembers message ids for 6 minutes (three of the longest intervals; its default is 90s), so a beat still travelling is not delivered twice. +- **One-sided links repaired from beats.** iroh-gossip's HyParView can lose the one reply that completes a link. Each beat lists its sender's neighbors; a neighbor whose beats leave this node out twice in a row is joined again. +- **Peer scores.** As in GossipSub, each node scores its peers: credit for messages a neighbor delivered, a squared penalty for invalid frames it delivered. Below −20 a peer is graylisted: what it delivers is dropped, it is not joined, and the node joins other peers when it has fewer than two good neighbors. Failed fetches are counted apart: three recent ones make the node fetch from other peers for a while, never graylist (a restarting peer fails fetches without misbehaving). Every counter decays each beat. `GET /api/net` lists the scores. +- **Details on focus.** What beats leave out (devices, the full probe report, processes with their status, services, the rolling summary, store, full stats and transport) is fetched for the node a HUD focuses (`GET /api/details?node_id=…`, which asks that node over `dialtone/fetch/1` and keeps the answer for 10s). +- **Peers that go silent are forgotten.** A peer pruned from the mesh is no longer a join candidate (seeds stay), so a node short of neighbors does not keep dialing dead peers. +- **Seeds follow the mesh.** About once a minute (every 12 beats) a node saves the peers it hears as its seeds in `config.json`: seeds it still hears stay first, other live peers fill up to 8, silent ones are dropped (a node that hears nobody keeps what it had). A node that restarts after the member it joined through has left still reaches the mesh. + +`./dialtone.sh test --here --only scale --scale N [--secs S]` starts N nodes on this machine, each given 3 random seeds, and reports how long until every node sees all N and the traffic per node (`GET /api/net`: socket bytes from iroh's counters, gossip messages, neighbors, and iroh-gossip's own counts of data frames, duplicates included, and control messages). Measured on one laptop: + +| Nodes | Before | After | +| ---: | :--- | :--- | +| 10 | converged in 4s; 56 Mbit/s in and out per node, 2001 connections opened | converged in 7s; 60 kbit/s per node, 4.6 neighbors | +| 30 | never converged (180s) | converged in 8s; 120 kbit/s per node | +| 50 | — | converged in 19s; 200 kbit/s per node | +| 100 | — | converged in 48s on one overloaded laptop | + +With gossip only and compact beats (envelope v6), 50 nodes on the same laptop converge in 12s at 42.5 kbit/s in per node (14 kbit/s of it gossip payload, 1.33 data frames per message delivered). On the live mesh a node takes in 0.76 kbit/s of gossip payload; the rest of its roughly 11 kbit/s is iroh's own upkeep of relay and paths. + +`./dialtone.sh test --only scale --scale N [--secs S]` does the same across the test VMs: N throwaway nodes on every VM in `fleet.local.env` (each runs the VM's installed binary), one mesh, seeds on any VM, links direct or through the relay. It waits 60s after convergence (`SCALE_WARMUP`), then reports traffic per VM, and stops every scale node afterwards (the VMs' own nodes are left alone); `./dialtone.sh test` ends with it, 10 nodes per VM. On the three VMs (US, Europe, Asia), 10 nodes on each (30 in all) converge in 17s and run at about 61 kbit/s in and out per node, of which 12.5 kbit/s is gossip payload (6 messages a second, 2.14 data frames per message delivered, 4.2 neighbors, none graylisted). Before the fleet moved to VMs, 20 nodes on each of three machines (60 in all) converged in 30 to 50s and settled in one of two states: most at about 420 kbit/s in per node, of which 133 kbit/s is beats (10 messages a second, about 2.1 data frames per message delivered); some at about 850 kbit/s, with 15 messages a second delivered and 2.8 frames each. The extra messages are not yet explained; old beats arriving up to 100s late (seen in node logs as replay rejects) suggest messages coming round again after iroh-gossip forgets their ids. Changing Plumtree's graft timeout made no difference. + +### Direct links (video) + +Gossip carries only what every node needs. Live media goes over a **link**: a direct QUIC connection between exactly two nodes (ALPN `dialtone/link/1`, `link.rs`), opened only while someone uses it. The allowlist decides who may open one, and iroh's hole punching finds a direct path; when two nodes cannot reach each other directly the link still runs through the relay and says so (`RELAY`, with more latency). + +```bash +# On the node with the camera: offer what arrives on 127.0.0.1:5000 as "cam". +dialtone link export cam --udp 127.0.0.1:5000 +ffmpeg -f dshow -i video="Cam Link 4K" -c:v libx264 -preset ultrafast -tune zerolatency \ + -g 30 -f mpegts "udp://127.0.0.1:5000?pkt_size=1128" # macOS: -f avfoundation -i "0" + +# On the viewer: deliver node "camera-node"'s "cam" to 127.0.0.1:6000 and play it. +dialtone link import camera-node/cam --udp 127.0.0.1:6000 +ffplay -fflags nobuffer -flags low_delay -framedrop udp://127.0.0.1:6000 + +dialtone link list # each link: DIRECT or RELAY, QUIC's Rtt, packets in / out / dropped +dialtone link close camera-node/cam +``` + +- **UDP** (`--udp`): on the exporting node, the address the source sends to; on the importing node, where packets are delivered. Packets travel as QUIC datagrams: unreliable and unordered, so a late frame is dropped instead of delaying the next one. A packet larger than the path allows is split into parts and put back together (a lost part drops its packet); `pkt_size=1128` (six MPEG-TS packets) keeps each one in a single datagram. Replies (RTCP) travel back to the source. +- **TCP** (`--tcp`): on the exporting node, a service to connect to (an RTSP or HTTP server); on the importing node, an address to listen on. Each TCP connection gets its own QUIC stream. +- Exports live in the running node until it restarts or `link close`; imports reconnect until closed. `GET /api/links` and `POST /api/links/{export,import,close}` are the API; the HUD lists this node's links with their path and Rtt. + +### Devices + +Every node lists the devices connected to it — cameras, microphones, speakers, keyboards, pointers (mice, trackpads), displays, printers, storage, Bluetooth devices and gamepads — using the OS's own view: `system_profiler` on macOS, `Get-PnpDevice` on Windows, `/sys` and `/proc` on Linux. Only each device's kind, name, bus (`built-in`, `usb`, `bluetooth`, `hid`, `display`, ...) and a short detail are kept; serial numbers and device IDs are dropped. + +```bash +./dialtone devices # table of this machine's devices +./dialtone devices --json # the same as JSON +curl -s http://127.0.0.1:8788/api/devices | jq +``` + +A running node lists its devices every 60 seconds. They are not gossiped: a peer asks for them when its HUD focuses the node (`GET /api/details?node_id=…`), and the HUD lists them under the node table; the tour's `DEV` step describes them. Device names (for example a Bluetooth headset named after its owner) are visible to every allowlisted node that asks. + +--- + +## 7. Supervised Processes + +### Keep a store Blob Running as a Daemon Process + +Once an executable binary or script is stored in the local store (`~/.dialtone/blobs`), you can configure `dialtone` to stage it into `~/.dialtone/run/-` (`chmod 0755`) and supervise it as a child process of the daemon: + +```bash +API_TOKEN=$(cat ~/.dialtone/api-token) + +# Spawn and supervise a store blob as a child process of dialtone +curl -X POST http://127.0.0.1:8788/api/processes/blob \ + -H "Authorization: Bearer $API_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "stats-blob-process", + "digest": "<64-hex-digest>", + "desired_state": "running", + "args": ["--interval", "5"], + "env": ["PROCESS_MODE=live"] + }' + +# Inspect live supervised processes (status, PID, restart_count, sha256) +curl -s http://127.0.0.1:8788/api/processes + +# Stop a supervised blob process cleanly +curl -X POST http://127.0.0.1:8788/api/processes/blob \ + -H "Authorization: Bearer $API_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "stats-blob-process", + "digest": "<64-hex-digest>", + "desired_state": "stopped" + }' + +# Remove it: stop it, forget its spec and delete its staged program +# (on the node that deployed it to the mesh, this removes every copy) +curl -X POST http://127.0.0.1:8788/api/processes \ + -H "Authorization: Bearer $API_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"name": "stats-blob-process", "desired_state": "removed"}' +``` + +- **Crash Auto-Respawn**: Every second (and on process status queries), the daemon checks all managed child PIDs via `try_wait()`. If a process with `"desired_state": "running"` exits or crashes, `dialtone` increments `restart_count`, re-stages the verified store blob, and spawns a fresh child PID automatically. +- **Environment Sanitization**: the node's own `DIALTONE_*` / `DAEMON_V1_*` variables (such as `DIALTONE_SECRET`) are removed from every process's environment, and a spec's `env` entries with those prefixes are ignored. +- **Restart Persistence**: process definitions are saved to `~/.dialtone/config.json` and automatically re-staged and started when `dialtone` boots. + +## 8. HTTP API Quick Reference + +All `POST` routes require `Authorization: Bearer ` (or `X-Dialtone-Token: `) matching `~/.dialtone/api-token`. + +Requests are parsed with `httparse`. The API refuses what it never needs: `Transfer-Encoding` (501), missing, duplicate or conflicting `Content-Length` values and bodies shorter than declared (400), bodies over 2 MiB (413), and request heads over 64 KiB or with more than 64 headers (431). Query values are percent-decoded. + +| Method & Path | Description | +| :--- | :--- | +| `GET /` | The HUD (served with a per-response Content-Security-Policy nonce) | +| `GET /hud/...` | The HUD's static files (`app.js`, `style.css`, vendored three.js and h3-js) | +| `GET /health` | `{"status": "ok", "node": ..., "peers": ..., "boot_stages": ...}` | +| `GET /api/config` (`/api/boot-status`) | Boot stages, mesh config (`derived_keys` redacted), store path | +| `POST /api/mesh/join` | Join or switch the channel of the running node | +| `POST /api/daemon/install` | Install the daemon (OS login service) | +| `GET /api/state` | Full node state | +| `GET /api/mesh` | Every node's latest beat, the Rtt matrix and Services | +| `POST /api/blob` | Put a base64 blob in the store (`~/.dialtone/blobs`) | +| `GET /api/blob?digest=...` | Blob bytes and metadata (`HEAD` also supported) | +| `POST /api/blob/share` | Put a blob in the store and return its `iroh-blobs://ticket/...` | +| `POST /api/blob/pull` | Pull a blob by ticket over QUIC into the store | +| `GET /api/processes` | Supervised processes with live PID / status | +| `GET /api/devices` | Devices connected to this node (cameras, microphones, keyboards, ...) | +| `POST /api/processes/blob` | Stage a program blob (or ticket) and run / stop it as a process; `"deploy_to_mesh": true` announces it to the mesh (`"deploy_targets"` to name nodes) | +| `POST /api/processes` | Same, and `{"name": ..., "desired_state": "removed"}` stops a process and forgets it (mesh-deployed copies follow) | +| `POST /api/probe` | Run one probe now, `{"all": true}` for a full probe (`GET` returns the latest); nodes check the mesh every 30s | +| `POST /api/restart` | Exit so the node's service starts it again on the binary now at its path (`dialtone join ` uses it to replace a running node on Windows) | +| `GET /api/net` | Traffic since boot: socket bytes in and out, connections, gossip messages, neighbors, iroh-gossip data and control frames, and peer scores | +| `GET /api/details?node_id=…` | A node's devices and full probe report, fetched from that node (kept 10s) | + + +--- + +## 9. Environment Variables & Local Paths + +| Variable / Path | Default | Purpose | +| :--- | :--- | :--- | +| `DIALTONE_STATE_DIR` / `DIALTONE_HOME` | `~/.dialtone` | Root state directory for config, identity, blobs, and staged executables | +| `DIALTONE_IROH_SECRET_KEY_FILE` | `~/.dialtone/iroh-secret-key` | Persistent 32-byte Ed25519 Iroh endpoint secret key (`0600` permissions) | +| `DIALTONE_API_TOKEN` | `~/.dialtone/api-token` | Bearer token required for all `POST` control API routes (and required when `--listen` is non-loopback) | +| `DIALTONE_HUD_DIR` | *(unset)* | Serve the HUD from this directory (e.g. `src/hud`) instead of the copy in the binary, uncached: HUD edits show on a browser reload with no rebuild or restart | +| `DIALTONE_CHANNEL` | `dialtone` | Default gossip channel name when `--channel` is not passed | +| `DIALTONE_SECRET` (`DIALTONE_SECRET_KEY`) | *(unset)* | Channel secret used to derive Argon2id `v2` channel keys on boot | +| `~/.dialtone/config.json` | — | Host-local mesh config (`0600`): Argon2id `derived_keys` (no plaintext secret), `seeds`, `allowlist`, `used_invite_nonces`, and supervised process specs | +| `~/.dialtone/api-token` | — | Auto-generated 256-bit local HTTP control API bearer token (`0600`) | +| `~/.dialtone/blobs/` | — | Blob store (iroh-blobs `FsStore`; blobs named by `sha256/` tags) | +| `~/.dialtone/run/` | — | Staged `0755` executables spawned by the blob process supervisor | +| `DIALTONE_AUTO_UPDATE` | *(on)* | `0` stops a node updating itself to new releases | +| `DIALTONE_RELEASE_URL` | GitHub releases | Where a node looks for releases (a mirror); they must still be signed with the release key | +| `DIALTONE_UPDATE_CHECK_SECS` | `3600` | How often a node asks for the latest release | +| `~/.dialtone/update.json` | — | Self-update state: the release on trial, the one kept, versions rolled back | +| `~/.dialtone/bin/dialtone.prev` | — | The binary that ran before the last update (what a rollback restores) | + +--- + +## 10. Working on dialtone: `./dialtone.sh` + +The Rust developer tasks are a small crate, `xtask/`, and `./dialtone.sh ` is the one entry point (a one-line wrapper for `cargo run -p xtask`). Those tasks need no Python, jq or curl; `test`, `dev` and `deploy` reach the test VMs with the system's `ssh` / `scp`, and `git` runs the leak gate. Only the `dialtone` binary is distributed and run. + +`cargo test` covers each capability with real iroh endpoints (signed gossip between two nodes, blob pulls through the node's downloader, the handshake allowlist, a two-node probe, the supervisor and the API), and runs real nodes from the built binary on every OS: `tests/node.rs` (one node: CLI, secrets, allowlist, API auth, supervisor, blobs, probe, one-shot runs) and `tests/e2e.rs` (three nodes: mesh, gossip only in steady state, probes, mesh deploys, a direct link, a stopped node caught, an open channel joined by invite, a node that started while its seed was down, a seed that restarted) and `tests/update.rs` (self-update from a signed release: a healthy one kept, one that panics or never gets healthy rolled back, a node updated from a peer, a node with no service restarting itself; not on macOS, where the test releases would be unsigned). + +**Rust runtime testing goes through one command, `./dialtone.sh test`.** The separate [installer fixture tests](install.md#installer-tests) use Python and run on each native CI platform without starting nodes. With no options it runs every test end to end on Linux VMs, never on the machine you type on: that machine only lints, packs the sources and drives the VMs over SSH. Options pick one part, or run on this machine instead (GitHub CI runs `test --here`). + +```bash +./dialtone.sh test # everything: lint here; on the build VM the whole cargo test + # suite and the release build; the rejoin test; every VM + # installs that build and must pass its gossip probe on exactly + # that binary, then a full probe; then 10 scale nodes per VM + # as one mesh +./dialtone.sh test --scale 20 # ... with 20 scale nodes per VM (--scale 0 skips them) +./dialtone.sh test --only lint # leak gate (no host names / NodeIds in git), domain language, + # fmt and clippy +./dialtone.sh test --only suite # just cargo test, on the build VM +./dialtone.sh test --only suite -- --test e2e # just the three-node tests (anything after -- goes + # to cargo test) +./dialtone.sh test --only rejoin # a node on the previous signed release joins the live channel + # by invite, goes away, rejoins and must update itself to the + # newest release, having heard of it in a peer's beat +./dialtone.sh test --only scale --scale 20 --secs 60 # just the scale test on the VMs' installed + # build: convergence time and traffic per node per VM +./dialtone.sh test --only probes # every VM's latest probe in the live mesh; fails unless all pass +./dialtone.sh test --here # on this machine instead: lint, cargo test, release build +./dialtone.sh test --here --only scale --scale 30 # 30 nodes on this machine; fails above + # SCALE_BUDGET_KBPS kbit/s in or out per node when set +``` + +Two more tasks look after the VMs; neither tests anything: + +```bash +./dialtone.sh dev # set up every VM for development: C toolchain, pkg-config, git, curl (apt) + # and Rust (rustup) with rustfmt and clippy; skips what is already there +./dialtone.sh dev user@10.0.0.9 # ... or any machine you can SSH to +./dialtone.sh deploy # build on the build VM and install on every VM, waiting for every probe + # (`test` already deploys the build it tested) +./dialtone.sh deploy --tag v0.5.1 # every VM downloads that release instead (SHA-256 checked) +``` + +The VMs come from `fleet.local.env` next to the script. It is never committed (`*.local.env` is ignored), so host names and addresses stay on your machine. Each VM runs a node as the systemd user service `dialtone` (`dialtone daemon install`); the build VM keeps its cargo target directory between runs, so only what changed is rebuilt, and every other VM gets the build VM's binary (so all VMs share its OS and architecture). + +```bash +FLEET_NODES="vm-alpha vm-beta vm-gamma" # every VM; deploy waits for all of their probes +BUILD_NODE="vm-alpha" # builds and runs the test suite (default: the first) +SSH_vm_alpha="-i $HOME/.ssh/id_vm user@203.0.113.10" # SSH options and destination +SSH_vm_beta="user@203.0.113.11|-J vm-alpha user@10.0.0.2" # alternatives; the first that answers wins +SSH_vm_gamma="user@203.0.113.12" +``` + +To check a single running node by hand, `./dialtone probe --all` runs every probe check on it: mesh, neighbors, beats, store, pulls from peers, programs and security. + +**Releasing.** Bump `version` in `Cargo.toml`, commit, and push a tag `vX.Y.Z`. After the assets are available, update the default version in both installer scripts and the install documentation, keeping the published platform table accurate. The release workflow builds every binary with `./dialtone.sh release build ` (the same command builds one here), then `./dialtone.sh release manifest` signs `dialtone-release.json` with the `DIALTONE_RELEASE_KEY` repository secret (it refuses a key whose public half is not the one in `src/update.rs`). Running nodes pick the release up within the hour, or within a beat once any peer runs it. + +**Build profiles.** `cargo build --release` is the everyday optimized build (no LTO, parallel and incremental codegen): `./dialtone.sh`, GitHub CI and deploys use it, and a one-file change rebuilds in about a second. Published binaries are built with `cargo build --profile dist` (size-optimized, fat LTO), which takes about a minute and only runs when a version is tagged. diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 0000000..4acd323 --- /dev/null +++ b/docs/install.md @@ -0,0 +1,117 @@ +# Installing Dialtone + +The [README](../README.md) has the one-command installers. The scripts in the `main` source branch default to **v0.5.3**, not a moving `latest/download` alias. They download the binary and its `.sha256` from the same explicit tag, validate the complete checksum record and expected filename, compare SHA-256, and only then replace the executable. Repeating the installation is safe. Failed downloads, missing or malformed checksums, and hash mismatches leave an existing executable unchanged. Temporary files are cleaned up on normal exit and errors, except recovery files retained after a failed Windows rollback. + +Windows replacement keeps an independent copy of the previous executable as well as passing a backup path to `File.Replace`. If replacement partially fails, the installer restores the independent copy. If the OS also prevents restoration, the installer fails and prints the retained `INSTALL_DIR\.dialtone-install-\dialtone.previous.exe` recovery path and destination. Keep that directory. After resolving the reported file/permission error, copy the recovery file to the printed destination; do not run an unknown partial replacement. The installer never deletes this recovery copy when rollback fails. + +The scripts install only the executable. They do not run it, access node state, join channels, open ports, register services, edit PATH, or request administrator privileges. The default directory is separate from the node's managed `~/.dialtone/bin` directory. Choose a directory you own; do not point the installer at a running node's managed binary. A locked executable on Windows causes installation to fail without deleting it. + +## Supported platforms + +| OS / architecture | Asset at the v0.5.3 release | Requirements | +| --- | --- | --- | +| Linux x86_64 / amd64 | `dialtone-linux-x86_64` | Static musl binary | +| Linux aarch64 / arm64 | `dialtone-linux-arm64` | GNU/glibc runtime; not musl/Alpine | +| macOS aarch64 / arm64 | `dialtone-macos-arm64` | Apple Silicon; a Rosetta shell is detected with `sysctl` | +| Windows AMD64 / x86_64 | `dialtone-windows-x86_64.exe` | Windows PowerShell 5.1 or PowerShell 7; the one-line bootstrap needs the built-in `curl.exe` (Windows 10 1803+, Windows 11, Server 2019+) | + +The Unix installer needs `curl`, standard POSIX utilities, and either `sha256sum` (Linux) or `shasum` (macOS). Windows uses .NET HTTP downloads and SHA-256. Its download handler explicitly enables TLS 1.2, including Windows PowerShell 5.1; any process-wide .NET TLS setting used for older Framework handlers is restored on success and failure. No machine-wide TLS settings change. An HTTPS connection to GitHub and its release asset hosts is required. Local policy may require inspection or approval before downloaded scripts can run; follow that policy without changing machine-wide execution settings. + +The release pipeline builds exactly these four targets. The installers reject unsupported OS/architecture selections. Windows requires both its machine environment registry value (from the shared `HKLM\SYSTEM` view) and shell architecture to identify AMD64; an unknown architecture fails closed. This avoids relying on an [emulated shell's processor report](https://learn.microsoft.com/en-us/windows/arm/apps-on-arm-x86-emulation#detecting-emulation) alone. ARM64/unknown registry results with an AMD64 shell are tested by deterministic injection on x64. **Actual Windows ARM64 hardware and emulated PowerShell rejection have not been tested.** There is no Intel macOS, Windows ARM64, or 32-bit release URL to use. Native build and runtime coverage would be required before adding support. You can try a [source build](#build-from-source) on an unsupported target, but it is not a verified release platform. + +An exact minimum glibc version for the existing ARM64 asset has not been verified from its ELF symbol requirements. The GNU target and build runner alone do not establish that minimum. If its loader reports a missing glibc version, build on your target system or use a compatible system; do not substitute the x86_64 musl binary on ARM64. + +## Download and inspect + +The bootstrap scripts live in the source repository; v0.5.3 release assets do **not** contain `install.sh` or `install.ps1`. The short README commands trust the current `main` script over HTTPS. + +The Windows command fetches the script with the built-in `curl.exe` (Windows 10 1803+, Windows 11, Server 2019+), which uses the OS TLS stack, so Windows PowerShell 5.1's legacy .NET TLS default does not apply to the bootstrap. Write `curl.exe`, not `curl`: in Windows PowerShell 5.1, `curl` is an alias for `Invoke-WebRequest`. Both one-line commands keep the whole script in memory (no temporary file) and run it only if the download succeeded: the Unix form with `&&` after the assignment, the Windows form by checking `$LASTEXITCODE` before `iex`. A failed or cut-off download (for example, a connection that closes before the promised length) therefore runs nothing and fails, even if the bytes received would parse. From `cmd.exe`, run `powershell -NoProfile -Command "$s = curl.exe -fsSL https://raw.githubusercontent.com/timcash/dialtone/main/install.ps1 | Out-String; if ($LASTEXITCODE) { throw 'install.ps1 download failed' }; iex $s"`. + +Without `curl.exe` (older Windows), use PowerShell's own download with TLS 1.2 enabled for the session: + +```powershell +& { $tls = [Net.ServicePointManager]::SecurityProtocol; try { + [Net.ServicePointManager]::SecurityProtocol = $tls -bor [Net.SecurityProtocolType]::Tls12 + irm https://raw.githubusercontent.com/timcash/dialtone/main/install.ps1 -ErrorAction Stop | iex +} finally { [Net.ServicePointManager]::SecurityProtocol = $tls } } +``` + +Download it first to review it: + +```sh +curl -fsSL https://raw.githubusercontent.com/timcash/dialtone/main/install.sh -o install.sh +less install.sh +sh install.sh +``` + +```powershell +curl.exe -fsSLo install.ps1 https://raw.githubusercontent.com/timcash/dialtone/main/install.ps1 +Get-Content -LiteralPath .\install.ps1 +& .\install.ps1 +``` + +For a reproducible bootstrap, replace `main` in the script URL with a full commit SHA that contains the installers, obtained from [repository history](https://github.com/timcash/dialtone/commits/main/). Check out or inspect that commit before executing. The original v0.5.3 source tag predates these scripts, so it cannot supply a pinned installer script. Pinning the script source and pinning the binary version are separate choices. + +## Advanced options + +After downloading and reviewing the script: + +```sh +sh install.sh --version v0.5.3 --install-dir "$HOME/Applications/Dialtone tools" +# Or pass options through the one-command form: +sh -c 's=$(curl -fsSL https://raw.githubusercontent.com/timcash/dialtone/main/install.sh) && eval "$s"' sh --version v0.5.3 --install-dir "$HOME/Applications/Dialtone tools" +``` + +```powershell +& .\install.ps1 -Version v0.5.3 -InstallDir "$HOME\Applications\Dialtone tools" +# Or pass options through the one-command form: +$s = curl.exe -fsSL https://raw.githubusercontent.com/timcash/dialtone/main/install.ps1 | Out-String; if ($LASTEXITCODE) { throw 'install.ps1 download failed' }; & ([ScriptBlock]::Create($s)) -Version v0.5.3 -InstallDir "$HOME\Applications\Dialtone tools" +``` + +Both scripts also accept `DIALTONE_VERSION` and `DIALTONE_INSTALL_DIR` environment variables; explicit options take precedence. Versions must be explicit tags such as `v0.5.3` (or a prerelease tag); `latest` is deliberately rejected. An unavailable tag or asset fails without changing an existing executable. Custom directories can contain spaces and may be relative to your current directory. PowerShell resolves them against its current FileSystem provider location, including after `Set-Location`, rather than the process working directory. They must be writable by your user. + +For a trusted release mirror, `DIALTONE_RELEASE_BASE_URL` replaces `https://github.com/timcash/dialtone/releases`. It must serve `download//` and `download//.sha256` over HTTPS. HTTP is accepted only for `127.0.0.1` fixture servers. This changes the source of first-install integrity data, so use only a mirror you trust. It does not change the node's `DIALTONE_RELEASE_URL` or signed update verification. + +## PATH + +You can always use the quoted full path shown in the README. For the default install directory, add it to the **current session** explicitly: + +```sh +export PATH="$HOME/.local/bin:$PATH" +dialtone --help +``` + +```powershell +$env:Path = "$HOME\.local\bin;" + $env:Path +dialtone --help +``` + +For a custom directory, substitute that exact directory. To keep the change in future sessions, add the shell command once to your shell's startup file (`~/.profile` for login sh/bash, `~/.zprofile` for login zsh), or add the directory through Windows **Edit environment variables for your account → User variables → Path** and open a new terminal. PowerShell users may instead place the session command in their existing `$PROFILE`. The installer never silently changes user or system settings. + +If another Dialtone is already on PATH, `command -v dialtone` (Unix) or `Get-Command dialtone -All` (PowerShell) shows what will run. Use the full new path when you need to choose the installed version explicitly. + +## Manual binary download and trust + +You can download a binary and its adjacent `.sha256` directly from the [v0.5.3 release](https://github.com/timcash/dialtone/releases/tag/v0.5.3). Pick the exact asset from the platform table and download both from that **same tag**. Compare its SHA-256 with the 64 hex characters in the checksum file using `sha256sum`, `shasum -a 256`, or `Get-FileHash -Algorithm SHA256`. Confirm that the checksum record names exactly the intended asset. Do not execute or replace an existing binary if either download or verification fails. The scripts automate these steps and atomic replacement. + +First-install SHA-256 detects corruption using checksums fetched over HTTPS from the same release source. It is **not independent publisher-signature verification**. Trusting that source and the bootstrap script is part of installation. Running nodes separately require the release-key-signed manifest for automatic updates; these installers do not disable or weaken that check. + +`--version` / `-Version` selects the version installed now. Running `~/.local/bin/dialtone up` (or the Windows/custom-directory equivalent) starts an **unmanaged** foreground node; that binary does not self-update. `update::Paths::managed` permits self-updates only for a binary inside the node's state-directory `bin` (normally `~/.dialtone/bin`). Explicitly joining with an invite or running `daemon install` creates and starts that managed copy, which can then receive signed automatic updates. The original `.local/bin` copy remains unchanged. To keep the managed node at a chosen version, set `DIALTONE_AUTO_UPDATE=0` in its environment before starting it (and in its service environment if applicable). See [update settings and state](guide.md#9-environment-variables--local-paths). + +## Build from source + +From the repository root, install a Rust toolchain and the native C build tools for your OS, then run: + +```sh +cargo build --locked --release -p dialtone +``` + +The executable is `target/release/dialtone` (`target\release\dialtone.exe` on Windows). This only builds; explicitly run or copy the binary when ready. On architectures without published releases, dependency compilation and runtime behavior still need validation. See the [developer guide](guide.md#10-working-on-dialtone-dialtonesh) for the existing checks and release process. + +## Installer tests + +`python tests/installers.py` (Python 3.10+) runs the native installer against an in-process local HTTP fixture release. It never runs a downloaded binary or a real Dialtone command. The repository entrypoint also exposes this as `./dialtone.sh test --here --only installers`; options after `--` go to the fixture runner. This explicit installer task requires Python; the existing Rust runtime test tasks are unchanged. On Windows, run it once with `--powershell powershell` and once with `--powershell pwsh`. On Unix, it also simulates target selection with `uname`/`sysctl` fixtures; this verifies selection, not those architectures' binaries. `--shell ` can exercise those selection tests under Git Bash on Windows, which is not native Linux/macOS coverage. + +CI runs the fixture tests on native Linux x86_64 and ARM64, macOS ARM64, and Windows x86_64 with both PowerShell versions. The payloads are fixtures, so these jobs test installer behavior and native target selection, not execution of release binaries. Linux ARM64 release building remains in the release matrix. No native Intel macOS or Windows ARM64 support is claimed. + +The opt-in `python tests/installers.py --live-release Installers.test_live_release_https` (add `--powershell powershell` on Windows) downloads the actual v0.5.3 release into an isolated custom directory and checks the installed bytes again against the published `.sha256`. On Windows it starts from a legacy process TLS default and checks that the TLS state is restored. Only after verification does it run `dialtone --help`, with isolated `HOME`, `USERPROFILE` and `DIALTONE_STATE_DIR`. It never runs `up`, `join`, `daemon` or `probe`, and never contacts a node. CI runs it on native Linux x86_64 and ARM64, macOS ARM64 and Windows x64, separately from the offline fixtures. A network-blocked local run must be reported as pending, not counted as a pass. diff --git a/install.ps1 b/install.ps1 new file mode 100644 index 0000000..b4aba3f --- /dev/null +++ b/install.ps1 @@ -0,0 +1,158 @@ +# Download only. Compatible with Windows PowerShell 5.1 and PowerShell 7. +[CmdletBinding()] +param( + [string]$Version = $(if ($env:DIALTONE_VERSION) { $env:DIALTONE_VERSION } else { 'v0.5.3' }), + [string]$InstallDir = $(if ($env:DIALTONE_INSTALL_DIR) { $env:DIALTONE_INSTALL_DIR } else { Join-Path $HOME '.local\bin' }) +) + +# Small file-operation boundaries let local tests reproduce partial Windows +# replacement errors without changing the registry or using a real executable. +function Get-DialtoneMachineArchitecture { + [Microsoft.Win32.Registry]::GetValue( + 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment', + 'PROCESSOR_ARCHITECTURE', $null) +} + +function Replace-DialtoneExecutable($Source, $Destination, $Backup) { + [IO.File]::Replace($Source, $Destination, $Backup) +} + +function Restore-DialtoneExecutable($Backup, $Destination) { + # Copy, never move: keep the independent recovery copy if restoration fails. + [IO.File]::Copy($Backup, $Destination, $true) +} + +function Install-Dialtone { + $ErrorActionPreference = 'Stop' + $downloadDir = $null + $stageDir = $null + $keepRecovery = $false + $previousTls = [Net.ServicePointManager]::SecurityProtocol + try { + if ([Environment]::OSVersion.Platform -ne [PlatformID]::Win32NT) { + throw 'Unsupported OS: use install.sh on Linux or macOS.' + } + # An emulated shell can report AMD64 on ARM64. Also require the machine + # environment from the shared HKLM\SYSTEM registry view; fail if unknown. + $arch = $env:PROCESSOR_ARCHITEW6432 + if (-not $arch) { $arch = $env:PROCESSOR_ARCHITECTURE } + $machineArch = Get-DialtoneMachineArchitecture + if ($arch -ne 'AMD64' -or $machineArch -ne 'AMD64') { + throw "Unsupported Windows architecture: $machineArch (shell: $arch). Only x86_64 is published; see docs/install.md." + } + if ($Version -cnotmatch '\Av[0-9]+\.[0-9]+\.[0-9]+(-[A-Za-z0-9][A-Za-z0-9.-]*)?\z') { + throw 'Version must be a tag such as v0.5.3.' + } + if ([string]::IsNullOrWhiteSpace($InstallDir)) { throw 'Install directory is empty.' } + $provider = $null + $drive = $null + $destinationDir = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($InstallDir, [ref]$provider, [ref]$drive) + if ($provider.Name -ne 'FileSystem') { throw 'InstallDir must use the FileSystem provider.' } + $releaseBase = 'https://github.com/timcash/dialtone/releases' + if ($env:DIALTONE_RELEASE_BASE_URL) { $releaseBase = $env:DIALTONE_RELEASE_BASE_URL.TrimEnd('/') } + $baseUri = [Uri]$releaseBase + if (-not $baseUri.IsAbsoluteUri -or ($baseUri.Scheme -ne 'https' -and + -not ($baseUri.Scheme -eq 'http' -and $baseUri.Host -eq '127.0.0.1'))) { + throw 'Release base must use HTTPS (or loopback HTTP for tests).' + } + $asset = 'dialtone-windows-x86_64.exe' + # Both requests use this one validated tag, never latest/download. + $url = "$releaseBase/download/$Version/$asset" + $downloadDir = Join-Path ([IO.Path]::GetTempPath()) ('dialtone-install-' + [Guid]::NewGuid().ToString('N')) + $null = [IO.Directory]::CreateDirectory($downloadDir) + $binary = Join-Path $downloadDir $asset + $checksum = Join-Path $downloadDir 'checksum' + # HttpClient is available on both supported PowerShell versions. Disable + # automatic redirects so HTTPS can never silently downgrade to HTTP. + Add-Type -AssemblyName System.Net.Http + $handler = New-Object System.Net.Http.HttpClientHandler + $handler.AllowAutoRedirect = $false + # .NET Framework may default to TLS 1.0 in stock Windows PowerShell 5.1. + # Prefer the handler's own setting; older Framework handlers use the + # process-wide ServicePointManager setting, restored on every exit. + [Net.ServicePointManager]::SecurityProtocol = $previousTls -bor [Net.SecurityProtocolType]::Tls12 + if ($handler.PSObject.Properties['SslProtocols']) { + $handler.SslProtocols = [Security.Authentication.SslProtocols]::Tls12 + } + $client = New-Object System.Net.Http.HttpClient($handler) + $client.Timeout = [TimeSpan]::FromSeconds(300) + try { + foreach ($item in @(@($url, $binary), @("$url.sha256", $checksum))) { + $uri = [Uri]$item[0] + for ($redirects = 0; ; $redirects++) { + if ($uri.Scheme -ne 'https' -and -not + ($baseUri.Scheme -eq 'http' -and $uri.Scheme -eq 'http' -and $uri.Host -eq '127.0.0.1')) { + throw 'Refusing insecure download redirect.' + } + # Buffer the response so HttpClient.Timeout covers the body + # as well as headers on .NET Framework (PowerShell 5.1). + $response = $client.GetAsync($uri).GetAwaiter().GetResult() + try { + if ([int]$response.StatusCode -in 301, 302, 303, 307, 308) { + if ($redirects -ge 5 -or -not $response.Headers.Location) { throw 'Invalid download redirect.' } + $uri = New-Object Uri($uri, $response.Headers.Location) + continue + } + $null = $response.EnsureSuccessStatusCode() + $stream = [IO.File]::Create($item[1]) + try { $null = $response.Content.CopyToAsync($stream).GetAwaiter().GetResult() } finally { $stream.Dispose() } + break + } finally { $response.Dispose() } + } + } + } finally { $client.Dispose(); $handler.Dispose() } + $record = [Text.Encoding]::ASCII.GetString([IO.File]::ReadAllBytes($checksum)) + $pattern = '\A([0-9a-fA-F]{64}) ' + [Regex]::Escape($asset) + '\r?\n\z' + if ($record -cnotmatch $pattern) { throw 'Invalid checksum record.' } + $expected = $Matches[1] + $hasher = [Security.Cryptography.SHA256]::Create() + $stream = [IO.File]::OpenRead($binary) + try { $actual = [BitConverter]::ToString($hasher.ComputeHash($stream)).Replace('-', '') } + finally { $stream.Dispose(); $hasher.Dispose() } + if ($actual -ne $expected) { + throw 'SHA-256 mismatch; previous install preserved.' + } + if ((Get-Item -LiteralPath $binary).Length -eq 0) { throw 'Empty binary.' } + + $null = [IO.Directory]::CreateDirectory($destinationDir) + $destination = Join-Path $destinationDir 'dialtone.exe' + $stageDir = Join-Path $destinationDir ('.dialtone-install-' + [Guid]::NewGuid().ToString('N')) + $null = [IO.Directory]::CreateDirectory($stageDir) + $staged = Join-Path $stageDir 'dialtone.exe' + [IO.File]::Copy($binary, $staged) + if ([IO.File]::Exists($destination)) { + # ReplaceFile can fail AFTER removing the destination (e.g. 1176). + # Keep an independent copy in addition to its own backup argument. + $recovery = Join-Path $stageDir 'dialtone.previous.exe' + [IO.File]::Copy($destination, $recovery) + $keepRecovery = $true + $replaceBackup = Join-Path $stageDir 'dialtone.replaced.exe' + try { + Replace-DialtoneExecutable $staged $destination $replaceBackup + } catch { + $replaceError = $_ + try { + Restore-DialtoneExecutable $recovery $destination + $keepRecovery = $false + } catch { + $keepRecovery = $true + throw "Replacement and restore failed. Previous executable kept at '$recovery'. Copy it to '$destination' after resolving the file error. Restore error: $_; replacement error: $replaceError" + } + throw "Replacement failed; previous executable restored. $replaceError" + } + $keepRecovery = $false + } else { + [IO.File]::Move($staged, $destination) + } + Write-Host "Installed $Version to $destination" + Write-Host 'No node started. Add the install directory to your PATH, or use the full path.' + Write-Host 'See https://github.com/timcash/dialtone/blob/main/docs/install.md' + } finally { + [Net.ServicePointManager]::SecurityProtocol = $previousTls + # Only our GUID-named temporary children are removed, never InstallDir. + if ($downloadDir) { Remove-Item -LiteralPath $downloadDir -Recurse -Force -ErrorAction SilentlyContinue } + if ($stageDir -and -not $keepRecovery) { Remove-Item -LiteralPath $stageDir -Recurse -Force -ErrorAction SilentlyContinue } + } +} + +Install-Dialtone diff --git a/install.sh b/install.sh new file mode 100644 index 0000000..c349f98 --- /dev/null +++ b/install.sh @@ -0,0 +1,102 @@ +#!/bin/sh +# Download only. No node, login service, configuration, or PATH changes. +# Keep execution at the end: a truncated curl | sh must not begin an install. +main() { + set -eu + version=${DIALTONE_VERSION:-v0.5.3} + install_dir=${DIALTONE_INSTALL_DIR:-"$HOME/.local/bin"} + release_base=${DIALTONE_RELEASE_BASE_URL:-https://github.com/timcash/dialtone/releases} + download_dir= + stage_dir= + + die() { printf 'dialtone installer: %s\n' "$*" >&2; exit 1; } + cleanup() { + [ -z "$download_dir" ] || rm -rf -- "$download_dir" + [ -z "$stage_dir" ] || rm -rf -- "$stage_dir" + } + trap cleanup 0 + trap 'exit 1' 1 2 15 + + while [ "$#" -gt 0 ]; do + case "$1" in + --version|--install-dir) + [ "$#" -ge 2 ] || die "$1 needs a value" + case "$1" in + --version) version=$2 ;; + --install-dir) install_dir=$2 ;; + esac + shift 2 ;; + -h|--help) + printf '%s\n' 'Usage: sh install.sh [--version v0.5.3] [--install-dir DIR]' + return ;; + *) die "unknown option: $1" ;; + esac + done + # A single explicit tag supplies BOTH requests; never use latest/download. + case "$version" in *[!A-Za-z0-9.-]*) die 'version must be a tag such as v0.5.3' ;; esac + printf '%s\n' "$version" | LC_ALL=C grep -Eq '^v[0-9]+\.[0-9]+\.[0-9]+(-[A-Za-z0-9][A-Za-z0-9.-]*)?$' || die 'version must be a tag such as v0.5.3' + [ -n "$install_dir" ] || die 'install directory is empty' + case "$install_dir" in /*) ;; *) install_dir="$PWD/$install_dir" ;; esac + release_base=${release_base%/} + # HTTPS for GitHub/mirrors; plain HTTP is limited to local fixture servers. + case "$release_base" in + https://*) protocols='=https'; redirect_limit=5 ;; + http://127.0.0.1:*) + printf '%s\n' "$release_base" | LC_ALL=C grep -Eq '^http://127\.0\.0\.1:[0-9]+(/[^?#]*)?$' || die 'invalid loopback release base' + protocols='=http'; redirect_limit=0 ;; + *) die 'release base must use HTTPS (or loopback HTTP for tests)' ;; + esac + + os=$(uname -s) + arch=$(uname -m) + # A Rosetta shell still runs on Apple Silicon; select its native binary. + if [ "$os" = Darwin ] && [ "$arch" = x86_64 ] && [ "$(sysctl -n hw.optional.arm64 2>/dev/null || :)" = 1 ]; then + arch=arm64 + fi + case "$os/$arch" in + Linux/x86_64|Linux/amd64) asset=dialtone-linux-x86_64 ;; + Linux/aarch64|Linux/arm64) asset=dialtone-linux-arm64 ;; + Darwin/arm64|Darwin/aarch64) asset=dialtone-macos-arm64 ;; + *) die "unsupported platform: $os/$arch; see docs/install.md for source builds" ;; + esac + command -v curl >/dev/null 2>&1 || die 'curl is required' + if command -v sha256sum >/dev/null 2>&1; then + hash_tool=sha256sum + elif command -v shasum >/dev/null 2>&1; then + hash_tool=shasum + else + die 'sha256sum or shasum is required' + fi + + download_dir=$(mktemp -d "${TMPDIR:-/tmp}/dialtone-install.XXXXXXXX") + url="$release_base/download/$version/$asset" + curl --fail --silent --show-error --location --max-redirs "$redirect_limit" --proto "$protocols" --proto-redir "$protocols" --connect-timeout 15 --max-time 300 "$url" -o "$download_dir/binary" + curl --fail --silent --show-error --location --max-redirs "$redirect_limit" --proto "$protocols" --proto-redir "$protocols" --connect-timeout 15 --max-time 60 "$url.sha256" -o "$download_dir/checksum" + # Accept exactly the release pipeline's one-line sha256sum record, with the + # expected filename. Never let a checksum file choose a local path to read. + [ "$(wc -c < "$download_dir/checksum" | tr -d ' ')" = "$((67 + ${#asset}))" ] || die 'invalid checksum record' + [ "$(wc -l < "$download_dir/checksum" | tr -d ' ')" = 1 ] || die 'invalid checksum record' + LC_ALL=C grep -Eq "^[0-9a-fA-F]{64} $asset$" "$download_dir/checksum" || die 'invalid checksum record' + expected=$(cut -c 1-64 "$download_dir/checksum" | tr 'A-F' 'a-f') + if [ "$hash_tool" = sha256sum ]; then + actual=$(sha256sum < "$download_dir/binary") + else + actual=$(shasum -a 256 < "$download_dir/binary") + fi + actual=${actual%% *} + [ "$actual" = "$expected" ] || die 'SHA-256 mismatch; previous install preserved' + [ -s "$download_dir/binary" ] || die 'empty binary' + + # Stage on the destination filesystem so the final rename is atomic. Nothing + # touches the previous executable until all downloads and checks succeed. + mkdir -p -- "$install_dir" + [ ! -d "$install_dir/dialtone" ] || die 'destination is a directory' + stage_dir=$(mktemp -d "$install_dir/.dialtone-install.XXXXXXXX") + cp -- "$download_dir/binary" "$stage_dir/dialtone" + chmod 755 "$stage_dir/dialtone" + mv -f -- "$stage_dir/dialtone" "$install_dir/dialtone" + printf 'Installed %s to %s\n' "$version" "$install_dir/dialtone" + printf '%s\n' 'No node started. Add the install directory to your PATH, or use the full path.' 'See https://github.com/timcash/dialtone/blob/main/docs/install.md' +} + +main "$@" diff --git a/tests/installers.py b/tests/installers.py new file mode 100644 index 0000000..baee1b1 --- /dev/null +++ b/tests/installers.py @@ -0,0 +1,678 @@ +"""Offline installer integration tests. Never execute the fixture binaries. + +python tests/installers.py [--powershell powershell|pwsh] [--shell /path/to/sh] +""" + +import argparse +import hashlib +import http.server +import os +from pathlib import Path +import platform +import re +import shutil +import subprocess +import sys +import tempfile +import threading +import unittest + + +ROOT = Path(__file__).resolve().parents[1] +ASSETS = ( + "dialtone-linux-x86_64", + "dialtone-linux-arm64", + "dialtone-macos-arm64", + "dialtone-windows-x86_64.exe", +) +parser = argparse.ArgumentParser(description=__doc__) +parser.add_argument("--powershell", default="pwsh") +parser.add_argument("--shell", help="Run Unix selection/installer tests, even on Windows") +parser.add_argument("--live-release", action="store_true", help="Opt in to a real HTTPS release download; never executes it") +OPTIONS, UNITTEST_ARGS = parser.parse_known_args() +UNIX = os.name != "nt" or bool(OPTIONS.shell) + + +def shell_path(path): + value = str(path) + if os.name == "nt" and UNIX: + value = Path(path).as_posix() + if len(value) > 2 and value[1] == ":": + value = "/" + value[0].lower() + value[2:] + return value + + +class Fixture(http.server.BaseHTTPRequestHandler): + files = {} + requests = [] + redirects = {} + truncated = set() + + def do_GET(self): + self.requests.append(self.path) + if self.path in self.redirects: + self.send_response(302) + self.send_header("Location", self.redirects[self.path]) + self.end_headers() + return + body = self.files.get(self.path) + self.send_response(200 if body is not None else 404) + self.send_header("Content-Length", str(len(body or b"") + (10 if self.path in self.truncated else 0))) + self.end_headers() + if body: + self.wfile.write(body) + self.close_connection = True + + def log_message(self, *_args): + pass + + +class Installers(unittest.TestCase): + @classmethod + def setUpClass(cls): + cls.server = http.server.ThreadingHTTPServer(("127.0.0.1", 0), Fixture) + cls.thread = threading.Thread( + target=lambda: cls.server.serve_forever(poll_interval=0.05), daemon=True + ) + cls.thread.start() + + @classmethod + def tearDownClass(cls): + cls.server.shutdown() + cls.server.server_close() + cls.thread.join() + + def setUp(self): + # All generated state is inside this worktree, including installer temps. + self.temp = tempfile.TemporaryDirectory(prefix=".installer-tests-", dir=ROOT) + self.addCleanup(self.temp.cleanup) + self.root = Path(self.temp.name) + self.home = self.root / "home with spaces" + self.home.mkdir() + self.tmp = self.root / "temp with spaces" + self.tmp.mkdir() + self.destination = self.home / "custom tools" + self.ps_injection = "" + self.ps_prefix = "" + self.ps_finally = "" + self.env = os.environ.copy() + # Let each PowerShell edition discover its own standard modules instead + # of inheriting the hosting edition's module paths. + self.env.pop("PSModulePath", None) + for key in list(self.env): + if key.startswith("DIALTONE_"): + del self.env[key] + self.env.update( + HOME=str(self.home), + USERPROFILE=str(self.home), + TMPDIR=str(self.tmp), + TMP=str(self.tmp), + TEMP=str(self.tmp), + DIALTONE_STATE_DIR=str(self.home / "node state"), + DIALTONE_RELEASE_BASE_URL=f"http://127.0.0.1:{self.server.server_port}/releases", + NO_PROXY="127.0.0.1", + no_proxy="127.0.0.1", + ) + if UNIX: + self.env["HOME"] = shell_path(self.home) + self.env["TMPDIR"] = shell_path(self.tmp) + Fixture.files = {} + Fixture.requests = [] + Fixture.redirects = {} + Fixture.truncated = set() + self.payloads = {} + for version in ("v0.5.3", "v1.2.3-rc.1"): + for asset in ASSETS: + # Deliberately inert payloads, never real Dialtone nodes. + body = f"#!/bin/sh\nexit 91\n# {version} {asset}\n".encode() + self.payloads[version, asset] = body + path = f"/releases/download/{version}/{asset}" + Fixture.files[path] = body + Fixture.files[path + ".sha256"] = ( + f"{hashlib.sha256(body).hexdigest()} {asset}\n".encode() + ) + self.os = platform.system() + self.arch = platform.machine().lower() + self.shim = self.root / "shim tools" + self.shim.mkdir() + self.env["DIALTONE_TEST_TOOL_PATH"] = shell_path(self.shim) + if UNIX: + self.driver = OPTIONS.shell or shutil.which("sh") + if not self.driver: + self.fail("sh is required") + self.asset = self.native_unix_asset() + else: + self.driver = shutil.which(OPTIONS.powershell) + if not self.driver: + self.fail(f"{OPTIONS.powershell} is required; do not silently skip native coverage") + self.asset = "dialtone-windows-x86_64.exe" + + def native_unix_asset(self): + if self.os == "Linux" and self.arch in ("x86_64", "amd64"): + return "dialtone-linux-x86_64" + if self.os == "Linux" and self.arch in ("aarch64", "arm64"): + return "dialtone-linux-arm64" + if self.os == "Darwin" and self.arch in ("aarch64", "arm64"): + return "dialtone-macos-arm64" + if OPTIONS.shell: + self.simulate("Linux", "x86_64") + return "dialtone-linux-x86_64" + self.fail(f"No native release asset for {self.os}/{self.arch}") + + def simulate(self, system, arch, apple_silicon="0"): + # Fake selection only, never pretend the downloaded fixture is a native binary. + for name, content in ( + ("uname", f'case "$1" in -s) echo {system};; -m) echo {arch};; *) exit 1;; esac'), + ("sysctl", f"echo {apple_silicon}"), + ): + script = self.shim / name + script.write_text("#!/bin/sh\n" + content + "\n", encoding="utf-8", newline="\n") + script.chmod(0o755) + + @property + def installed(self): + return self.destination / ("dialtone" if UNIX else "dialtone.exe") + + @property + def asset_path(self): + return f"/releases/download/v0.5.3/{self.asset}" + + def run_installer(self, *args, ok=True, default_dir=False, piped=False, error=None, recovery=False, timeout=45): + if UNIX: + # Git's bin/sh.exe launcher prepends its own tools to PATH. Put the + # selection shims first inside the shell, after that launcher runs. + command = [self.driver, "-c", 'export PATH="$DIALTONE_TEST_TOOL_PATH:$PATH"; exec sh "$@"', "installer-test"] + if piped: + command += ["-s", "--"] + else: + command += [shell_path(ROOT / "install.sh")] + if not default_dir: + command += ["--install-dir", shell_path(self.destination)] + else: + command = [self.driver, "-NoLogo", "-NoProfile", "-NonInteractive"] + if piped: + command += ["-Command", "$input | Out-String | Invoke-Expression"] + self.env["DIALTONE_INSTALL_DIR"] = str(self.destination) + else: + # Exercise the README's in-memory script form, also on hosts + # whose local-file execution policy is Restricted. No policy changes. + def quote(value): + return "'" + str(value).replace("'", "''") + "'" + script = ROOT / "install.ps1" + if self.ps_injection: + # Inject local operation failures at function boundaries. + # The production installer has no test environment switches. + source = script.read_text(encoding="utf-8") + before, after = source.rsplit("\nInstall-Dialtone", 1) + script = self.root / "injected.ps1" + script.write_text(before + "\n" + self.ps_injection + "\nInstall-Dialtone" + after, encoding="utf-8") + invocation = "& ([ScriptBlock]::Create([IO.File]::ReadAllText(" + quote(script) + ")))" + if not default_dir: + invocation += " -InstallDir " + quote(self.destination) + invocation += " " + " ".join(quote(arg) if not arg.startswith("-") else arg for arg in args) + if self.ps_finally: + invocation = "try { " + invocation + " } finally { " + self.ps_finally + " }" + invocation = self.ps_prefix + invocation + command += ["-Command", invocation] + if UNIX or piped: + command += list(args) + source = None + if piped: + source = (ROOT / ("install.sh" if UNIX else "install.ps1")).read_bytes() + result = subprocess.run( + command, cwd=self.root, env=self.env, input=source, + stdout=subprocess.PIPE, stderr=subprocess.STDOUT, timeout=timeout, + ) + output = result.stdout.decode(errors="replace") + self.assertEqual(result.returncode == 0, ok, output) + if error: + self.assertIn(error.lower(), output.lower(), output) + self.assertFalse((self.home / "node state").exists(), output) + self.assertFalse((self.home / ".dialtone").exists(), output) + self.assertEqual(list(self.tmp.iterdir()), [], output) + if self.destination.is_dir() and not recovery: + self.assertEqual(list(self.destination.glob(".dialtone-install*")), [], output) + return output + + def old_install(self): + self.destination.mkdir(exist_ok=True) + self.installed.write_bytes(b"previous executable") + + def assert_preserved(self): + self.assertEqual(self.installed.read_bytes(), b"previous executable") + + def test_native_install_and_repeat_with_spaces(self): + self.run_installer() + self.assertEqual(self.installed.read_bytes(), self.payloads["v0.5.3", self.asset]) + if UNIX and os.name != "nt": + self.assertTrue(self.installed.stat().st_mode & 0o111) + self.run_installer() + self.assertEqual(self.installed.read_bytes(), self.payloads["v0.5.3", self.asset]) + self.assertEqual(Fixture.requests, [self.asset_path, self.asset_path + ".sha256"] * 2) + + def test_piped_bootstrap(self): + self.run_installer(piped=True) + self.assertEqual(self.installed.read_bytes(), self.payloads["v0.5.3", self.asset]) + + @unittest.skipUnless(UNIX, "curl | sh truncation guard") + def test_truncated_pipe_does_not_install(self): + source = (ROOT / "install.sh").read_text(encoding="utf-8").split('\nmain "$@"')[0] + result = subprocess.run( + [self.driver], input=source.encode(), env=self.env, cwd=self.root, + stdout=subprocess.PIPE, stderr=subprocess.STDOUT, timeout=10, + ) + self.assertEqual(result.returncode, 0, result.stdout) + self.assertEqual(Fixture.requests, []) + self.assertFalse(self.destination.exists()) + + def test_environment_defaults_and_explicit_option_precedence(self): + self.env["DIALTONE_INSTALL_DIR"] = shell_path(self.home / "unused") + self.env["DIALTONE_VERSION"] = "v9.9.9" + args = ["--version", "v1.2.3-rc.1"] if UNIX else ["-Version", "v1.2.3-rc.1"] + self.run_installer(*args) + self.assertEqual(self.installed.read_bytes(), self.payloads["v1.2.3-rc.1", self.asset]) + self.assertFalse((self.home / "unused").exists()) + self.assertTrue(all("/v1.2.3-rc.1/" in path for path in Fixture.requests)) + + def test_default_directory(self): + # PowerShell's automatic HOME comes from the user profile, not env:HOME. + # A launcher explicitly sets it to our isolated test home. + if not UNIX: + quoted = str(self.home).replace("'", "''") + script = str(ROOT / "install.ps1").replace("'", "''") + invocation = f"Set-Variable HOME '{quoted}' -Force; & ([ScriptBlock]::Create([IO.File]::ReadAllText('{script}')))" + result = subprocess.run( + [self.driver, "-NoProfile", "-NonInteractive", "-Command", invocation], + env=self.env, cwd=self.root, capture_output=True, timeout=45, + ) + self.assertEqual(result.returncode, 0, result.stdout + result.stderr) + else: + self.run_installer(default_dir=True) + target = self.home / ".local" / "bin" / ("dialtone" if UNIX else "dialtone.exe") + self.assertEqual(target.read_bytes(), self.payloads["v0.5.3", self.asset]) + self.assertEqual(list(self.tmp.iterdir()), []) + + def test_custom_directory_environment(self): + self.env["DIALTONE_INSTALL_DIR"] = shell_path(self.destination) + self.env["DIALTONE_VERSION"] = "v1.2.3-rc.1" + self.run_installer(default_dir=True) + self.assertEqual(self.installed.read_bytes(), self.payloads["v1.2.3-rc.1", self.asset]) + + def test_relative_directory_with_spaces(self): + self.destination = self.root / "relative tools" + self.env["DIALTONE_INSTALL_DIR"] = "relative tools" + self.run_installer(default_dir=True) + self.assertEqual(self.installed.read_bytes(), self.payloads["v0.5.3", self.asset]) + + @unittest.skipIf(UNIX, "PowerShell provider location") + def test_provider_location_differs_from_process_directory(self): + provider_dir = self.root / "provider location" + provider_dir.mkdir() + self.destination = provider_dir / "relative tools" + self.env["DIALTONE_INSTALL_DIR"] = "relative tools" + quoted = str(provider_dir).replace("'", "''") + self.ps_prefix = f"Set-Location -LiteralPath '{quoted}'; " + self.run_installer(default_dir=True) + self.assertEqual(self.installed.read_bytes(), self.payloads["v0.5.3", self.asset]) + self.assertFalse((self.root / "relative tools").exists()) + + @unittest.skipIf(UNIX, "PowerShell provider validation") + def test_non_filesystem_install_directory_rejected(self): + self.ps_prefix = "Set-Location Env:; " + self.env["DIALTONE_INSTALL_DIR"] = "DIALTONE_NOT_A_DIRECTORY" + self.run_installer(default_dir=True, ok=False, error="must use the FileSystem provider") + self.assertEqual(Fixture.requests, []) + + def test_default_versions_match_scripts_and_docs(self): + sh = (ROOT / "install.sh").read_text(encoding="utf-8") + ps = (ROOT / "install.ps1").read_text(encoding="utf-8") + shell_default = re.search(r'version=\$\{DIALTONE_VERSION:-(v[^}]+)\}', sh).group(1) + windows_default = re.search(r"DIALTONE_VERSION } else { '(v[^']+)'", ps).group(1) + self.assertEqual(shell_default, windows_default) + self.assertIn(f'Install **{shell_default}**', (ROOT / "README.md").read_text(encoding="utf-8")) + self.assertIn(f'default to **{shell_default}**', (ROOT / "docs/install.md").read_text(encoding="utf-8")) + self.assertIn((shell_default, self.asset), self.payloads) + + @unittest.skipUnless(UNIX and os.name != "nt", "Unix filenames with backslash/newline") + def test_odd_temp_directory_name(self): + self.tmp = self.root / "temp\\with\nnewline" + self.tmp.mkdir() + self.env["TMPDIR"] = str(self.tmp) + self.run_installer() + self.assertEqual(self.installed.read_bytes(), self.payloads["v0.5.3", self.asset]) + + def legacy_tls_setup(self): + self.ps_prefix = "[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls; $beforeTls = [Net.ServicePointManager]::SecurityProtocol; " + self.ps_finally = "if ([Net.ServicePointManager]::SecurityProtocol -ne $beforeTls) { throw 'TLS state leaked' }; Write-Host 'TLS_STATE_RESTORED'" + + @unittest.skipIf(UNIX, "PowerShell process TLS settings") + def test_tls_state_restored_on_success_and_failure(self): + self.legacy_tls_setup() + self.assertIn("TLS_STATE_RESTORED", self.run_installer()) + Fixture.files[self.asset_path] = b"bad binary" + self.assertIn("TLS_STATE_RESTORED", self.run_installer(ok=False, error="SHA-256 mismatch")) + + @property + def script_name(self): + return "install.sh" if UNIX else "install.ps1" + + def to_fixture(self, command): + # Point an exact documented command at the fixture copy of the script. + source_url = f"https://raw.githubusercontent.com/timcash/dialtone/main/{self.script_name}" + self.assertEqual(command.count(source_url), 1, command) + self.assertNotIn("\n", command.strip()) + return command.replace(source_url, f"http://127.0.0.1:{self.server.server_port}/bootstrap/{self.script_name}") + + def readme_bootstrap(self): + readme = (ROOT / "README.md").read_text(encoding="utf-8") + fence = "sh" if UNIX else "powershell" + self.env["DIALTONE_INSTALL_DIR"] = shell_path(self.destination) if UNIX else str(self.destination) + return self.to_fixture(re.search(r"```" + fence + r"\n(.*?)\n```", readme, re.S).group(1)) + + def run_bootstrap(self, command): + if UNIX: + argv = [self.driver, "-c", 'export PATH="$DIALTONE_TEST_TOOL_PATH:$PATH"; ' + command] + else: + argv = [self.driver, "-NoProfile", "-NonInteractive", "-Command", command] + result = subprocess.run(argv, cwd=self.root, env=self.env, capture_output=True, timeout=45) + output = (result.stdout + result.stderr).decode(errors="replace") + self.assertFalse((self.home / "node state").exists(), output) + self.assertEqual(list(self.tmp.iterdir()), [], output) + return result.returncode, output + + def test_readme_bootstrap(self): + Fixture.files["/bootstrap/" + self.script_name] = (ROOT / self.script_name).read_bytes() + command = self.readme_bootstrap() + if not UNIX: + self.legacy_tls_setup() + command = self.ps_prefix + "try { " + command + " } finally { " + self.ps_finally + " }" + for success in (True, False): + with self.subTest(bootstrap_download=success): + if not success: + del Fixture.files["/bootstrap/" + self.script_name] + code, output = self.run_bootstrap(command) + self.assertEqual(code == 0, success, output) + if not UNIX: + self.assertIn("TLS_STATE_RESTORED", output) + self.assertEqual(self.installed.read_bytes(), self.payloads["v0.5.3", self.asset]) + + def test_readme_bootstrap_truncated_script_does_not_install(self): + source = (ROOT / self.script_name).read_bytes() + call = b'\nmain "$@"' if UNIX else b"\nInstall-Dialtone" + cuts = { + "mid-function": source[:200], + "before-call": source[: source.rindex(call)], + # Every byte, parseable and complete, but the connection closes + # before the promised Content-Length: the download still failed. + "complete-but-short": source, + } + bootstrap = self.readme_bootstrap() + for label, body in cuts.items(): + with self.subTest(cut=label): + Fixture.files["/bootstrap/" + self.script_name] = body + Fixture.truncated = {"/bootstrap/" + self.script_name} + Fixture.requests = [] + code, output = self.run_bootstrap(bootstrap) + self.assertNotEqual(code, 0, output) + self.assertFalse(self.installed.exists(), output) + self.assertEqual([p for p in Fixture.requests if p.startswith("/releases/")], [], output) + + def test_documented_pinned_one_command_form(self): + Fixture.files["/bootstrap/" + self.script_name] = (ROOT / self.script_name).read_bytes() + docs = (ROOT / "docs/install.md").read_text(encoding="utf-8") + start = "sh -c 's=$(curl" if UNIX else "$s = curl.exe" + line = next(l for l in docs.splitlines() if l.startswith(start) and "v0.5.3" in l) + command = self.to_fixture(line.replace("v0.5.3", "v1.2.3-rc.1")) + if not UNIX: + # PowerShell's automatic $HOME comes from the profile; isolate it. + command = f"Set-Variable HOME '{str(self.home).replace(chr(39), chr(39) * 2)}' -Force; " + command + self.destination = self.home / "Applications" / "Dialtone tools" + code, output = self.run_bootstrap(command) + self.assertEqual(code, 0, output) + self.assertEqual(self.installed.read_bytes(), self.payloads["v1.2.3-rc.1", self.asset]) + + @unittest.skipUnless(OPTIONS.live_release, "Opt-in HTTPS release smoke test") + def test_live_release_https(self): + del self.env["DIALTONE_RELEASE_BASE_URL"] + if UNIX: + self.run_installer(timeout=330) + else: + self.legacy_tls_setup() + self.assertIn("TLS_STATE_RESTORED", self.run_installer(timeout=330)) + self.assertGreater(self.installed.stat().st_size, 1024 * 1024) + self.assertEqual(Fixture.requests, []) + # Independently re-check the installed bytes against the published record. + import urllib.request + url = f"https://github.com/timcash/dialtone/releases/download/v0.5.3/{self.asset}.sha256" + with urllib.request.urlopen(url, timeout=60) as response: + record = response.read().decode("ascii") + self.assertEqual(record, f"{hashlib.sha256(self.installed.read_bytes()).hexdigest()} {self.asset}\n") + # Only after verification: --help, which reads at most DIALTONE_STATE_DIR/config.json + # (absent here) and starts nothing. + result = subprocess.run( + [str(self.installed), "--help"], cwd=self.root, env=self.env, + stdout=subprocess.PIPE, stderr=subprocess.STDOUT, timeout=30, + ) + output = result.stdout.decode(errors="replace") + self.assertEqual(result.returncode, 0, output) + self.assertIn("usage: dialtone", output) + self.assertFalse((self.home / "node state").exists(), output) + self.assertFalse((self.home / ".dialtone").exists(), output) + + def test_corrupt_binary_preserves_previous(self): + self.old_install() + Fixture.files[self.asset_path] = b"corrupt binary" + self.run_installer(ok=False, error="SHA-256 mismatch") + self.assert_preserved() + + def test_missing_binary_preserves_previous(self): + self.old_install() + del Fixture.files[self.asset_path] + self.run_installer(ok=False) + self.assertEqual(Fixture.requests, [self.asset_path]) + self.assert_preserved() + + def test_missing_checksum_preserves_previous(self): + self.old_install() + del Fixture.files[self.asset_path + ".sha256"] + self.run_installer(ok=False) + self.assertEqual(Fixture.requests, [self.asset_path, self.asset_path + ".sha256"]) + self.assert_preserved() + + def test_truncated_download_preserves_previous(self): + self.old_install() + Fixture.truncated.add(self.asset_path) + self.run_installer(ok=False) + self.assertEqual(Fixture.requests, [self.asset_path]) + self.assert_preserved() + + def test_invalid_checksum_records_preserve_previous(self): + self.old_install() + checksum = Fixture.files[self.asset_path + ".sha256"] + variants = { + "empty": b"", + "html": b"not a checksum\n", + "short hash": b"ab12 " + self.asset.encode() + b"\n", + "non hex": b"g" * 64 + b" " + self.asset.encode() + b"\n", + "wrong hash": b"0" * 64 + b" " + self.asset.encode() + b"\n", + "wrong filename": checksum.replace(self.asset.encode(), b"other-file"), + "extra record": checksum + checksum, + "trailing data": checksum + b"x", + "no final newline": checksum.rstrip(b"\n"), + "byte order mark": b"\xef\xbb\xbf" + checksum, + "embedded null": checksum[:10] + b"\0" + checksum[11:], + } + for label, record in variants.items(): + with self.subTest(label=label): + Fixture.files[self.asset_path + ".sha256"] = record + self.run_installer(ok=False, error="SHA-256 mismatch" if label == "wrong hash" else "invalid checksum record") + self.assert_preserved() + + def test_empty_binary_rejected_even_with_matching_hash(self): + self.old_install() + Fixture.files[self.asset_path] = b"" + Fixture.files[self.asset_path + ".sha256"] = ( + f"{hashlib.sha256(b'').hexdigest()} {self.asset}\n".encode() + ) + self.run_installer(ok=False, error="empty binary") + self.assert_preserved() + + def test_first_install_failure_leaves_no_executable(self): + del Fixture.files[self.asset_path + ".sha256"] + self.run_installer(ok=False) + self.assertFalse(self.installed.exists()) + + def test_missing_version_and_bad_tag(self): + self.old_install() + for tag in ("v9.9.9", "latest", "v0.5.3/../v1.2.3", "v0.5.3?query"): + with self.subTest(tag=tag): + args = ["--version", tag] if UNIX else ["-Version", tag] + self.run_installer(*args, ok=False) + self.assert_preserved() + + def test_destination_directory_is_not_replaced(self): + self.installed.mkdir(parents=True) + sentinel = self.installed / "keep" + sentinel.write_bytes(b"keep") + self.run_installer(ok=False) + self.assertEqual(sentinel.read_bytes(), b"keep") + self.assertEqual(list(self.installed.iterdir()), [sentinel]) + + def test_replace_failure_preserves_previous(self): + self.old_install() + if UNIX: + # Simulate a final rename failure (e.g. permissions/filesystem). + script = self.shim / "mv" + script.write_text("#!/bin/sh\nexit 93\n", encoding="utf-8", newline="\n") + script.chmod(0o755) + self.run_installer(ok=False) + else: + # Real Windows sharing lock, not a mocked File.Replace call. + import ctypes + from ctypes import wintypes + create = ctypes.windll.kernel32.CreateFileW + create.argtypes = [wintypes.LPCWSTR, wintypes.DWORD, wintypes.DWORD, + wintypes.LPVOID, wintypes.DWORD, wintypes.DWORD, wintypes.HANDLE] + create.restype = wintypes.HANDLE + close = ctypes.windll.kernel32.CloseHandle + close.argtypes = [wintypes.HANDLE] + handle = create(str(self.installed), 0x80000000, 0, None, 3, 0, None) + self.assertNotEqual(handle, wintypes.HANDLE(-1).value) + try: + self.run_installer(ok=False) + finally: + close(handle) + self.assert_preserved() + + @unittest.skipIf(UNIX, "Windows partial ReplaceFile failure") + def test_destructive_partial_replace_rolls_back(self): + for operation in ( + "[IO.File]::Move($Destination, $Backup)", + "[IO.File]::Delete($Destination)", + "[IO.File]::Move($Destination, $Backup); [IO.File]::Copy($Source, $Destination)", + ): + with self.subTest(operation=operation): + self.old_install() + self.ps_injection = """ +function Replace-DialtoneExecutable($Source, $Destination, $Backup) { + %s + throw (New-Object ComponentModel.Win32Exception(1176)) +} +""" % operation + self.run_installer(ok=False, error="previous executable restored") + self.assert_preserved() + + @unittest.skipIf(UNIX, "Windows recovery copy retained after rollback failure") + def test_failed_rollback_keeps_recovery_and_reports_path(self): + self.old_install() + self.ps_injection = """ +function Replace-DialtoneExecutable($Source, $Destination, $Backup) { + [IO.File]::Move($Destination, $Backup) + throw (New-Object ComponentModel.Win32Exception(1176)) +} +function Restore-DialtoneExecutable($Backup, $Destination) { + throw 'Injected restore failure' +} +""" + output = self.run_installer(ok=False, error="previous executable kept at", recovery=True) + backups = list(self.destination.glob(".dialtone-install-*/dialtone.previous.exe")) + self.assertEqual(len(backups), 1, output) + self.assertEqual(backups[0].read_bytes(), b"previous executable") + # PowerShell may wrap the error display; remove whitespace for path comparison. + self.assertIn("".join(str(backups[0]).split()), "".join(output.split())) + self.assertIn("Injected restore failure", output) + + @unittest.skipIf(UNIX, "Deterministic native Windows architecture simulation") + def test_native_arm64_or_unknown_rejected_even_with_amd64_shell(self): + self.env["PROCESSOR_ARCHITECTURE"] = "AMD64" + self.env["PROCESSOR_ARCHITEW6432"] = "" + for architecture in ("'ARM64'", "$null"): + with self.subTest(machine=architecture): + self.ps_injection = "function Get-DialtoneMachineArchitecture { " + architecture + " }" + self.run_installer(ok=False, error="unsupported Windows architecture") + self.assertEqual(Fixture.requests, []) + + def test_insecure_remote_base_is_rejected_before_download(self): + self.env["DIALTONE_RELEASE_BASE_URL"] = "http://example.invalid/releases" + self.run_installer(ok=False, error="release base must use HTTPS") + self.assertEqual(Fixture.requests, []) + + def test_redirect_to_asset_and_missing_redirect_target(self): + original = Fixture.files.pop(self.asset_path) + Fixture.files["/fixture-binary"] = original + Fixture.redirects[self.asset_path] = "/fixture-binary" + if UNIX: + # POSIX permits no redirects from its HTTP-only fixture mode, + # preventing a local fixture URL from redirecting off loopback. + self.old_install() + self.run_installer(ok=False, error="redirect") + self.assert_preserved() + else: + self.run_installer() + self.old_install() + Fixture.redirects[self.asset_path] = "/missing" + self.run_installer(ok=False) + self.assert_preserved() + + @unittest.skipUnless(UNIX, "Unix target selection simulation") + def test_simulated_supported_unix_selection(self): + for system, arch, silicon, asset in ( + ("Linux", "x86_64", "0", "dialtone-linux-x86_64"), + ("Linux", "aarch64", "0", "dialtone-linux-arm64"), + ("Darwin", "arm64", "1", "dialtone-macos-arm64"), + ("Darwin", "x86_64", "1", "dialtone-macos-arm64"), + ): + with self.subTest(system=system, arch=arch, rosetta=silicon): + self.simulate(system, arch, silicon) + self.run_installer() + self.assertEqual(self.installed.read_bytes(), self.payloads["v0.5.3", asset]) + + def test_unsupported_platforms_before_download(self): + self.old_install() + if UNIX: + variants = [("Darwin", "x86_64"), ("Linux", "armv7l"), ("FreeBSD", "x86_64"), ("MINGW64_NT", "x86_64")] + else: + variants = [("AMD64", "ARM64"), ("ARM64", ""), ("x86", "")] + for first, second in variants: + with self.subTest(platform=(first, second)): + if UNIX: + self.simulate(first, second) + else: + self.env["PROCESSOR_ARCHITECTURE"] = first + self.env["PROCESSOR_ARCHITEW6432"] = second + self.run_installer(ok=False, error="unsupported") + self.assert_preserved() + self.assertEqual(Fixture.requests, []) + + +if __name__ == "__main__": + mode = ( + "fixtures plus opt-in live HTTPS download (verified binary runs --help only)" + if OPTIONS.live_release else "fixtures only, no binary execution" + ) + print( + f"Installer tests: {'Unix via ' + (OPTIONS.shell or 'native sh') if UNIX else OPTIONS.powershell} " + f"on {platform.system()}/{platform.machine()}; {mode}.", + flush=True, + ) + unittest.main(argv=[sys.argv[0]] + UNITTEST_ARGS, verbosity=2) diff --git a/xtask/src/fleet.rs b/xtask/src/fleet.rs index 6affe2a..66c8c5e 100644 --- a/xtask/src/fleet.rs +++ b/xtask/src/fleet.rs @@ -25,7 +25,7 @@ impl Fleet { pub fn load() -> R { let file = std::env::var("FLEET_FILE").unwrap_or_else(|_| "fleet.local.env".into()); let text = std::fs::read_to_string(&file).map_err(|_| { - format!("{file} not found: it lists this fleet's VMs (see the dev tasks section of README.md)") + format!("{file} not found: it lists this fleet's VMs (see the dev tasks section of docs/guide.md)") })?; let home = crate::util::home().to_string_lossy().replace('\\', "/"); let mut vars: HashMap = HashMap::new(); diff --git a/xtask/src/main.rs b/xtask/src/main.rs index f0493a4..9f9dc4e 100644 --- a/xtask/src/main.rs +++ b/xtask/src/main.rs @@ -21,6 +21,8 @@ dialtone dev tasks: ./dialtone.sh build (what GitHub CI runs) --only lint just the leak gate, domain language, fmt and clippy --only suite just cargo test (on the build VM, or --here) + --only installers local installer fixtures only (Python 3.10+, no nodes); + after -- pass options to tests/installers.py --only rejoin a node on the previous signed release joins the live channel by invite, goes away, rejoins and must update itself from what its peers' beats say diff --git a/xtask/src/test.rs b/xtask/src/test.rs index 96c1097..7f20b91 100644 --- a/xtask/src/test.rs +++ b/xtask/src/test.rs @@ -6,7 +6,7 @@ use crate::fleet::{self, Fleet}; use crate::util::{cargo, run, say, R}; /// What `--only` can pick. -const PARTS: [&str; 5] = ["lint", "suite", "rejoin", "scale", "probes"]; +const PARTS: [&str; 6] = ["lint", "suite", "installers", "rejoin", "scale", "probes"]; struct Opts { here: bool, @@ -14,7 +14,7 @@ struct Opts { /// Scale nodes per VM, or on this machine with `--here`. scale: Option, secs: f64, - /// After `--`: passed to `cargo test`. + /// After `--`: passed to `cargo test` or the installer fixture runner. cargo: Vec, } @@ -64,6 +64,12 @@ pub fn test(args: &[String]) -> R<()> { let o = parse(args)?; match (o.only.as_deref(), o.here) { (Some("lint"), _) => crate::check_static(), + (Some("installers"), _) => { + say("Installer fixtures (local only, no node starts; needs Python 3.10+)"); + run(std::process::Command::new("python") + .arg("tests/installers.py") + .args(&o.cargo)) + } (None, true) => { crate::check_static()?; suite_here(&o.cargo)?;