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 fromiroh::endpoint::presets::Minimal, attachingPkarrPublisher,PkarrResolver, andDnsAddressLookuponly when explicitly enabled.P2pRelayMode::Defaultenables Pkarr lookup/publish on listeners while dialers never publish (publish_pkarr = false).parse_p2p_relay_modesmaps--p2p-relay(default,disabled, or1..=8repeatable URLs, acceptinghttps://or loopbackhttp://) toDefault,Disabled,Custom(String)(1URL), orCustomMany(Vec<String>)(2..=8URLs), targeting validated self-hostediroh-relayURLs without touchingn0Pkarr/DNS unless--p2p-pkarris opted in. Onwasm32-unknown-unknownbrowsers,WasmIrohStreambuilds frompresets::Minimaland only attaches read-onlyPkarrResolver::n0_dns()when no relay hint is provided. - Managed
iroh-relayauthentication (Option 2A &p2p-iroh-services): Custom relay pools accept static bearer tokens via--p2p-relay-token-fileorTENDRIL_P2P_RELAY_TOKEN(applied viaRelayMap::with_auth_token(...)). Enabling the optionalp2p-iroh-servicesCargo feature (--p2p-api-secret-fileorTENDRIL_P2P_API_SECRET) constructs short-lived lowercaseBASE32_NOPADRCAN capability tokens directly viairoh_services::caps::create_api_token_from_secret_keyontoEndpoint::builder(presets::Minimal)+RelayMap::with_auth_token(...), intentionally NOT callingIrohServicesPreset::apply(which pullspresets::N0Pkarr/DNS). Becauseirohlooks upauth_tokenstrictly by exact relay URL key inRelayMap, untrusted?relay=hints not configured inRelayMapreceiveauth_token = None. - Address hint privacy:
format_p2p_endpointomits direct?addr=socket hints by default (format_p2p_endpoint_with_addrscontrols explicit opt-in), andparse_p2p_endpoint_filteredunconditionally strips metadata/link-local IPs and filters private/reserved?addr=hints on relayed dialers. - Deterministic P2P routing key: Host listeners derive their
iroh::SecretKeydeterministically via single-block HKDF-SHA256 fromEndpointIdentity::static_key(derive_p2p_identity_seed, label"tendril/p2p/iroh-identity/v1") rather than persisting a second key file or regenerating an ephemeralEndpointIdon every reboot (--ephemeral-p2popts 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:
P2pStreamsurfaces the remote transportEndpointIdviaPathStream::peer_transport_id(), soPreAuthRateLimiter::try_acquire_for_streamandInboundRouterrate-limit pre-Noise P2P handshakes per remote PeerID alongside a per-EndpointIdconcurrent accept cap onP2pListener(MAX_CONCURRENT_ACCEPTS_PER_PEER = 4) instead of starving unrelated peers. - Stream instantiation (
TENDRIL_P2P_ALPN = "tendril/p2p/v1"): Because QUIC bidirectional streams created byopen_bi()are only surfaced on the remoteaccept_bi()after initial bytes arrive, dialers send a1-byte stream opener (0x54) immediately afteropen_bi(), andP2pListenervalidates it under a bounded timeout before admitting the stream. - Connection lifetime:
P2pListener,P2pDialer, andP2pStreamshare anArc<EndpointGuard>with explicitclose_now()teardown inP2pStream::close()andP2pDialer::close()so flushed QUIC frames andFINdeliver 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::startembedstendril_relay::RelayServerdirectly in-process for single-host zero-dependency relay fallback.Roster::update_relay_hints(crates/tendril-core/src/roster.rs) updatesentry.relay_hintsfor non-revoked peers while leavingstatic_pub,signing_pub,rotation_seq,state, andgrantsuntouched.- Persisted
StateStorerosters 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_modeevaluatesOverlayMode::{Disabled, Host, Helper, Auto}using file or environment variable credential references (auth_key_file/auth_key_env), never inline secrets.is_tailnet_ipidentifies100.64.0.0/10andfd7a:115c:a1e0::/48addresses.OverlayHelperListenerandOverlayHelperDialercommunicate solely over0o600Unix sockets inside0o700directories with bounded 1-line JSON control framing, avoiding localhost TCP port forwarding.broker(providers/broker.rs):BrokerListenervalidates exact HTTPGETrequest path (404mismatch) and optional request headers viasubtle::ConstantTimeEq(401mismatch) under pre-auth upgrade limits before exposing aWsBinaryPathStreambounded byMAX_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-runtimeverifies the 6-point provider contract, deterministic HKDF-derivedP2pListenerEndpointIdpersistence and rotation,peer_transport_idpre-auth rate limiting, and fullNoise_XXhfspairing/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,p2pcold-delay policy failover, andpublic -> self-hosted -> embeddedrelay_hintsmigration.tendril-cliverifies live subprocesstendril serve --embedded-relay --p2p-local --overlay --brokerpairing overirohP2P, identicaliroh://<endpoint_id>across host restarts, clean client endpoint shutdown, and dialing acrossP2p,Overlay,Broker, andRelay(EmbeddedRelay).bindings/web(TENDRIL_WEB_P2P_LIVE=1 node bindings/web/test/browser_e2e.mjs) verifies headless Chrome WASM (WasmIrohStreamoverws_stream_wasm+PkarrResolver::n0_dns()) pairing and dialing a livetendril serve --p2phost using a bareiroh://<endpoint_id>URI over publiciroh-relayWebSockets.- Physical 30-minute mobile battery draw (
Gate #11) requires dedicated iOS/Android hardware runs outside headless Linux CI.
Connections
Local graphLinked from
- Layering CRDT, sync, and group enginesUsing Tendril1. Keep one transport stack in the process“Tendril's six-rung provider ladder”
- Add six-rung path providers, iroh P2P, and embedded relayLogs“Six-rung path providers and relay ladder”
- Add sync-engine layering guide and Tailscale DERP topology notesLogs“Six-rung path providers and relay ladder”