From fae62892e062fc1cec94436395454a11bc991c39 Mon Sep 17 00:00:00 2001 From: tsunagi Date: Mon, 21 Sep 2026 12:17:01 +0100 Subject: [PATCH] Rename the --transport n0 value to relay and say what n0 means "n0" is Number 0, the company behind iroh, and the name leaked from iroh's own preset into this project's user interface, where it explains nothing. The value is now --transport relay, which says what it does; n0 stays as an accepted alias. Also spells out, in the CLI help, the README, the threat model and the TransportPolicy docs, whose infrastructure is involved: address records are published to and resolved from dns.iroh.link, and the fallback relays are Number 0's, in the US, EU and Asia-Pacific. Co-Authored-By: Claude Opus 5 (1M context) --- README.md | 19 ++++++++++--------- docs/threat-model.md | 5 +++-- src/bin/tsunagi.rs | 18 ++++++++++-------- src/config.rs | 17 ++++++++++++----- 4 files changed, 35 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index b3bfad8..04b119e 100644 --- a/README.md +++ b/README.md @@ -100,8 +100,8 @@ wireguard: tsunkkcp43lmdje on fd15:1d9e:fa21:f201:…/64 mtu 1100, 1/1 tunnel(s) Notes: - Only one side needs `--peer`; the link is bidirectional. -- The default `--transport n0` uses iroh's public address lookup and relays, so - two machines behind NAT find each other. `--transport local` keeps everything +- The default `--transport relay` uses iroh's public address lookup and relays, + so two machines behind NAT find each other. `--transport local` keeps everything on the local network. See *How peers find each other* below — it is worth understanding what gets published. - Without `CAP_NET_ADMIN`, add `--no-tun`: the mesh, the data links and the @@ -184,10 +184,10 @@ explicitly. Two different lookups are involved, and only one of them is this project's: **1. Resolving one endpoint's address — iroh's, and it works today.** -With `--transport n0` or `--transport direct`, iroh publishes a signed record -of this endpoint's addresses, keyed by its endpoint id, to Number 0's public -service (`dns.iroh.link`, over pkarr and DNS) and resolves other endpoints the -same way. That is why `--peer ` works with no address attached: +With `--transport relay` or `--transport direct`, iroh publishes a signed +record of this endpoint's addresses, keyed by its endpoint id, to the public +service run by Number 0 — "n0", the company behind iroh — at `dns.iroh.link`, +over pkarr and DNS, and resolves other endpoints the same way. That is why `--peer ` works with no address attached: iroh looks it up. None of that code is ours. **2. Finding who is in a network — ours, and it is still manual.** @@ -200,12 +200,13 @@ whatever those agents reach. What this means in practice: -- With `n0` or `direct`, **your endpoint id and IP addresses are published to a - public third-party service.** They are not secret, and the network secret is +- With `relay` or `direct`, **your endpoint id and IP addresses are published + to a public third-party service** (Number 0's, unless you change it). They are not secret, and the network secret is never published, but an observer of that service learns that your endpoint exists and where it is. `--transport local` publishes nothing. - A relay, when one is needed, sees the volume and timing of your traffic — not - its contents. + its contents. The default relays are Number 0's, in the US, EU and + Asia-Pacific. ## Storage diff --git a/docs/threat-model.md b/docs/threat-model.md index c25e5f5..cea0e61 100644 --- a/docs/threat-model.md +++ b/docs/threat-model.md @@ -43,8 +43,9 @@ Read this before relying on anything here. The protocol is in handshake. Use `NetworkSecret::generate()`. - **Public address publication.** With `TransportPolicy::N0Defaults` or `DirectOnly`, iroh publishes a signed record of this endpoint's addresses, - keyed by its endpoint id, to Number 0's public pkarr/DNS service, and - resolves peers through it. The network secret is never published and + keyed by its endpoint id, to the public pkarr/DNS service run by Number 0 + ("n0", the company behind iroh) at `dns.iroh.link`, and resolves peers + through it. The network secret is never published and membership cannot be inferred from a single record, but the endpoint's existence and its addresses become public. `LocalOnly` publishes nothing. - **Addresses and metadata are observable.** Anyone able to watch the network diff --git a/src/bin/tsunagi.rs b/src/bin/tsunagi.rs index 6aae50e..179ffe0 100644 --- a/src/bin/tsunagi.rs +++ b/src/bin/tsunagi.rs @@ -72,17 +72,19 @@ impl PathArgs { /// How much external connectivity machinery the endpoint may use. /// -/// `direct` and `n0` publish this endpoint's addresses, keyed by its endpoint -/// id, to Number 0's public lookup service, and resolve peers through it. -/// That is what makes `--peer ` work without an address. +/// `direct` and `relay` publish this endpoint's addresses, keyed by its +/// endpoint id, to the public lookup service run by Number 0 — the company +/// behind iroh — at `dns.iroh.link`, and resolve peers through it. That is +/// what makes `--peer ` work without an address. #[derive(Debug, Clone, Copy, ValueEnum)] enum Transport { /// Loopback and the local network only. Publishes nothing. Local, - /// Public address lookup, but no relays. + /// Public address lookup, direct paths only, no relays. Direct, - /// iroh's defaults: public address lookup plus the public n0 relays. - N0, + /// Public address lookup plus public relay fallback. The default. + #[value(alias = "n0")] + Relay, } impl From for TransportPolicy { @@ -90,7 +92,7 @@ impl From for TransportPolicy { match value { Transport::Local => TransportPolicy::LocalOnly, Transport::Direct => TransportPolicy::DirectOnly, - Transport::N0 => TransportPolicy::N0Defaults, + Transport::Relay => TransportPolicy::N0Defaults, } } } @@ -122,7 +124,7 @@ struct UpArgs { hostname: Option, /// How much external connectivity to use. - #[arg(long, value_enum, default_value_t = Transport::N0)] + #[arg(long, value_enum, default_value_t = Transport::Relay)] transport: Transport, /// A peer to contact, as `` or `@,...`. diff --git a/src/config.rs b/src/config.rs index 642bcf7..bcba814 100644 --- a/src/config.rs +++ b/src/config.rs @@ -89,12 +89,19 @@ pub enum TransportPolicy { /// Suitable for tests and for fully local deployments. #[default] LocalOnly, - /// No relays, but the n0 DNS/pkarr address lookup is enabled. - DirectOnly, - /// iroh's standard behaviour, including the public n0 relays. + /// Public address lookup, but no relays. /// - /// Public relays are fine for development; they carry no availability - /// guarantee. + /// Enables iroh's DNS/pkarr address lookup against the public service run + /// by Number 0 (the company behind iroh) at `dns.iroh.link`. This endpoint + /// publishes a signed record of its own addresses there, so peers can dial + /// it by endpoint id alone. + DirectOnly, + /// iroh's standard behaviour: public address lookup plus public relays. + /// + /// Maps to iroh's own `presets::N0`. As well as the address lookup above, + /// it uses Number 0's public relay servers as a fallback when a direct + /// path cannot be hole punched. They are fine for development and carry no + /// availability guarantee. N0Defaults, }