Six-rung path providers and relay ladder

Untrusted PathProvider implementations across all six Policy rungs, zero-setup iroh P2P discovery, scoped overlay IPC, embedded relays, and zero-re-pair hint migration.

Tendril treats every transport path as an untrusted byte pipe below hybrid post-quantum Noise (Noise_XXhfs_25519+MLKEM768_ChaChaPoly_SHA256). Phase 5 completes all six rungs of ProviderId inside tendril-runtime and exposes them in tendril-cli.

Provider ladder and dialing policy

Rung (ProviderId) Rank Implementation (tendril-runtime) Primary Use Case
local 0 LocalListener / LocalDialer (0o600 Unix socket) Same-host IPC between desktop/daemon processes
direct 1 DirectListener / DirectDialer (TCP) LAN or direct IP reachable sockets
overlay 2 OverlayListener / OverlayDialer, OverlayHelperListener / OverlayHelperDialer Tailnet CGNAT/ULA sockets or scoped 0o600 helper IPC
p2p 3 P2pListener / P2pDialer (iroh 1.5, gated behind p2p-iroh) Zero-setup NAT traversal with public relay/discovery fallback
relay 4 RelayListener / RelayDialer, EmbeddedRelay Stateless WebSocket relay (spec/relay-v1.md)
broker 5 BrokerListener / BrokerDialer (broker+ws:// / broker+wss://) Reverse-proxied or authenticated HTTPS/WSS tunnel adapter

PathPlanner (dial_with_policy) ranks candidates by (provider.rank(), !is_numeric_host, id) and enforces p2p_cold_delay_ms (500 ms default) before dialing p2p candidates alongside higher-priority local/direct/overlay candidates so fast local connections are never stalled by peer discovery.

Zero-setup P2P (p2p-iroh feature)

Enabling p2p-iroh on tendril-runtime (enabled by default in tendril-cli and tendril-ffi, and opt-in on tendril-wasm) compiles crates/tendril-runtime/src/providers/p2p.rs (native) or crates/tendril-wasm/src/p2p.rs (browser WASM) over iroh 1.5 (tls-ring, plus portmapper on native targets):

  • Relay modes (P2pRelayMode & P2pOptions): Constructed from iroh::endpoint::presets::Minimal, attaching PkarrPublisher, PkarrResolver, and DnsAddressLookup only when explicitly enabled. P2pRelayMode::Default enables Pkarr lookup/publish on listeners while dialers never publish (publish_pkarr = false). parse_p2p_relay_modes maps --p2p-relay (default, disabled, or 1..=8 repeatable URLs, accepting https:// or loopback http://) to Default, Disabled, Custom(String) (1 URL), or CustomMany(Vec<String>) (2..=8 URLs), targeting validated self-hosted iroh-relay URLs without touching n0 Pkarr/DNS unless --p2p-pkarr is opted in. On wasm32-unknown-unknown browsers, WasmIrohStream builds from presets::Minimal and only attaches read-only PkarrResolver::n0_dns() when no relay hint is provided.
  • Managed iroh-relay authentication (Option 2A & p2p-iroh-services): Custom relay pools accept static bearer tokens via --p2p-relay-token-file or TENDRIL_P2P_RELAY_TOKEN (applied via RelayMap::with_auth_token(...)). Enabling the optional p2p-iroh-services Cargo feature (--p2p-api-secret-file or TENDRIL_P2P_API_SECRET) constructs short-lived lowercase BASE32_NOPAD RCAN capability tokens directly via iroh_services::caps::create_api_token_from_secret_key onto Endpoint::builder(presets::Minimal) + RelayMap::with_auth_token(...), intentionally NOT calling IrohServicesPreset::apply (which pulls presets::N0 Pkarr/DNS). Because iroh looks up auth_token strictly by exact relay URL key in RelayMap, untrusted ?relay= hints not configured in RelayMap receive auth_token = None.
  • Address hint privacy: format_p2p_endpoint omits direct ?addr= socket hints by default (format_p2p_endpoint_with_addrs controls explicit opt-in), and parse_p2p_endpoint_filtered unconditionally strips metadata/link-local IPs and filters private/reserved ?addr= hints on relayed dialers.
  • Deterministic P2P routing key: Host listeners derive their iroh::SecretKey deterministically via single-block HKDF-SHA256 from EndpointIdentity::static_key (derive_p2p_identity_seed, label "tendril/p2p/iroh-identity/v1") rather than persisting a second key file or regenerating an ephemeral EndpointId on every reboot (--ephemeral-p2p opts out). The P2P key rotates automatically whenever the static Noise key rotates, and remains routing metadata only (never an authorization input).
  • Transport PeerID pre-auth rate limiting: P2pStream surfaces the remote transport EndpointId via PathStream::peer_transport_id(), so PreAuthRateLimiter::try_acquire_for_stream and InboundRouter rate-limit pre-Noise P2P handshakes per remote PeerID alongside a per-EndpointId concurrent accept cap on P2pListener (MAX_CONCURRENT_ACCEPTS_PER_PEER = 4) instead of starving unrelated peers.
  • Stream instantiation (TENDRIL_P2P_ALPN = "tendril/p2p/v1"): Because QUIC bidirectional streams created by open_bi() are only surfaced on the remote accept_bi() after initial bytes arrive, dialers send a 1-byte stream opener (0x54) immediately after open_bi(), and P2pListener validates it under a bounded timeout before admitting the stream.
  • Connection lifetime: P2pListener, P2pDialer, and P2pStream share an Arc<EndpointGuard> with explicit close_now() teardown in P2pStream::close() and P2pDialer::close() so flushed QUIC frames and FIN deliver cleanly before runtime shutdown.

Relay ladder and zero-re-pair migration

Applications can move between public relays, self-hosted tendril-relay containers (including Option 1A Tiers 1-3 admission with --allow-mailbox / --allow-mailboxes-file, --auth-secret-file / TENDRIL_RELAY_AUTH_SECRET, --issuer-pub + RelayTicket, and --auth-scope <all|register-only> across /v1/relay and /v2/relay), and in-process EmbeddedRelay instances without discarding existing Noise pins or signed grants:

  • EmbeddedRelay::bind_local / EmbeddedRelay::start embeds tendril_relay::RelayServer directly in-process for single-host zero-dependency relay fallback.
  • Roster::update_relay_hints (crates/tendril-core/src/roster.rs) updates entry.relay_hints for non-revoked peers while leaving static_pub, signing_pub, rotation_seq, state, and grants untouched.
  • Persisted StateStore rosters reload updated relay hints across restarts (public -> self-hosted -> embedded) and re-establish sessions with existing credentials (Gate #10).

Scoped overlay and broker adapters

  • overlay (providers/overlay.rs): select_overlay_mode evaluates OverlayMode::{Disabled, Host, Helper, Auto} using file or environment variable credential references (auth_key_file / auth_key_env), never inline secrets. is_tailnet_ip identifies 100.64.0.0/10 and fd7a:115c:a1e0::/48 addresses. OverlayHelperListener and OverlayHelperDialer communicate solely over 0o600 Unix sockets inside 0o700 directories with bounded 1-line JSON control framing, avoiding localhost TCP port forwarding.
  • broker (providers/broker.rs): BrokerListener validates exact HTTP GET request path (404 mismatch) and optional request headers via subtle::ConstantTimeEq (401 mismatch) under pre-auth upgrade limits before exposing a WsBinaryPathStream bounded by MAX_OUTER_FRAME_LEN.

External overlay, Tailscale DERP, and edge-proxy topologies

Deployment Topology Rung & Configuration Who Needs Overlay Client Relay & Protocol Behavior
Peer-to-peer on a tailnet overlay (overlay://<tailnet_ip>:<port> or 0o600 tsnet helper socket) Both peers tailscaled or tsnet attempts direct WireGuard UDP and falls back automatically to Tailscale's DERP relay fleet; Tendril still runs Noise_XXhfs and default-deny grants inside the stream
Host on tailnet, external browsers or phones relay (tailscale funnel <port> -> standalone tendril-relay --listen 127.0.0.1:<port> --host <node>.<tailnet>.ts.net --trusted-proxy 127.0.0.1/32; --embedded-relay --relay-host <node>.<tailnet>.ts.net binds an ephemeral 127.0.0.1:0 port without --trusted-proxy) or native broker (tendril serve --broker 127.0.0.1:<port>) Host only Funnel terminates TLS at Tailscale's edge and traverses DERP to the host; /v1/relay and /v2/relay serve both @tendril-sdk/web browsers and native clients (verifying challenge.host), while broker+wss:// serves native BrokerDialer clients (or custom sans-I/O WASM WebSocket wrappers)
Cloudflare Tunnel, Caddy, or Nginx ingress relay (tendril-relay --listen 127.0.0.1:<port> --host <public_host> --trusted-proxy <CIDR>) or native broker (broker+wss://) Neither Edge proxy terminates TLS and forwards binary WebSockets to tendril-relay (browser + native) or BrokerListener (native BrokerDialer, optional constant-time header secret)
Raw derp*.tailscale.com URL in --p2p-relay or --relay Unsupported N/A iroh-relay (p2p) diverged from Tailscale's Upgrade: DERP X25519 packet protocol onto WebSockets and Ed25519 node keys, tendril-relay speaks /v1/relay and /v2/relay JSON challenges, and Tailscale's public DERP fleet admits coordinated tailnet nodes only

Verification status

  • tendril-runtime verifies the 6-point provider contract, deterministic HKDF-derived P2pListener EndpointId persistence and rotation, peer_transport_id pre-auth rate limiting, and full Noise_XXhfs pairing/confirm/mint/data/rekey/revoke lifecycle across all six rungs (local, direct, overlay, p2p, relay, broker), select_overlay_mode + scoped Unix helper IPC, broker rejection paths, p2p cold-delay policy failover, and public -> self-hosted -> embedded relay_hints migration.
  • tendril-cli verifies live subprocess tendril serve --embedded-relay --p2p-local --overlay --broker pairing over iroh P2P, identical iroh://<endpoint_id> across host restarts, clean client endpoint shutdown, and dialing across P2p, Overlay, Broker, and Relay (EmbeddedRelay).
  • bindings/web (TENDRIL_WEB_P2P_LIVE=1 node bindings/web/test/browser_e2e.mjs) verifies headless Chrome WASM (WasmIrohStream over ws_stream_wasm + PkarrResolver::n0_dns()) pairing and dialing a live tendril serve --p2p host using a bare iroh://<endpoint_id> URI over public iroh-relay WebSockets.
  • Physical 30-minute mobile battery draw (Gate #11) requires dedicated iOS/Android hardware runs outside headless Linux CI.

Connections

Local graph

Linked from