Skip to main content

Module iroh_substrate

Module iroh_substrate 

Source
Expand description

Iroh transport substrate — the PRIMARY production transport for Epic #131 (ZMQ → moq-net + iroh), promoted to default in #410.

Builds a shared iroh::Endpoint from an Ed25519 node key and wires an [iroh::protocol::Router] with two ALPN slots:

  • ALPN_MOQ_LITE (moql) — moq-net session handler, wired by the daemon spawner (#282) to dispatch into the shared global moq_stream::Origin for the streaming plane.
  • ALPN_HYPRSTREAM_RPC (hyprstream-rpc/1) — raw Cap’n Proto bidi handler, wired by the daemon spawner (#282) to terminate IrohRpcProtocolHandler for the RPC plane.

Phase 1 shipped the substrate, a NoopHandler placeholder, and a smoke test verifying that two endpoints can dial each other directly and open a bidi stream on each ALPN. As of #410, production code DOES consume this module: the daemon spawner (hyprstream-service::service::spawner) binds one IrohSubstrate per QUIC-enabled service as the PRIMARY production endpoint (on by default; [quic] iroh = false opts out to quinn-only). The real moql and hyprstream-rpc/1 handlers are threaded in by the spawner (#282). OAuth binds a reach-only endpoint whose inbound ALPNs remain refused until independently verified application/session proof is wired.

§D3 — iroh pkarr is LIVENESS-ONLY, never an authority source (#895)

iroh’s presets::N0 discovery publishes classical pkarr records — signed-but-not-encrypted packets — onto the open BitTorrent mainline DHT to advertise reach (home relay + direct addresses) for a NodeId. As of #895 (epic #880 Track D / D3) this is the contract for pkarr in hyprstream:

  • Reach hint, not authority. A pkarr record is an unverified dial candidate: “NodeId N claims it is reachable at relay R / addr A.” It is signed by N’s Ed25519 key, so it is integrity-protected as a reach claim — but that says nothing about which federated identity (capsule, did:web, did:key) controls N, what its PQ key material is, or whether it may be admitted. No identity / trust / admission decision is ever derived from a pkarr record. Connection::remote_id() authenticates only the carrier endpoint. Application identity requires independently resolved current keys plus fresh inside-carrier proof (#1027).
  • Two riders, one DHT, one trust posture. Both iroh pkarr and the at9p mainline locator (#890 / C2) ride the same mainline DHT. Only at9p is zero-trust: its records are content-addressed (did:at9p:<cid512>) and made trustworthy by the GATE pipeline (canon → hash → composite-sig), so the DHT is an untrusted locator for at9p, never a trust root. pkarr, by contrast, is classical-only and trusts the DHT to carry the publisher’s reach claim verbatim — fine for liveness, fatal as an authority source.
  • Not removed. pkarr stays — it is genuinely useful for NAT traversal / liveness (“is this peer dialable right now?”). D3 only strips (and forbids re-deriving) authority from it; it does not disable publication.

Enforcement seams: the dial path (crate::dial) resolves addresses from a NodeId as an address, never trusting pkarr for identity. Admission does not consume NodeId, remote_id(), or pkarr. The wasm pkarr output is typed as an unverified reach hint ([crate::iroh_peer::PkarrReachHint]) so it cannot be conflated with verified reach.

The #385 metadata-leak side channel (a passive observer can enumerate which NodeIds are reachable and correlate lookup traffic) is unaffected by this demotion — pkarr is still public. Its mitigation is oblivious-relay (#361); until then, operators that consider the side channel actionable should run a self-hosted iroh-dns-server configured through the owned endpoint builder.

Structs§

EchoHandler
Test-only handler that accepts one bidi stream, reads one length-prefixed message, echoes it back, then closes. Used by the Phase 1 smoke test to verify that both ALPN slots route correctly.
IrohSubstrate
Two-plane iroh substrate: one shared QUIC endpoint, two ALPN-dispatched protocol handlers.
NoopHandler
Placeholder protocol handler that accepts an incoming connection and immediately returns. Used until Phase 2 / Phase 3 wire the real handlers.
OwnedIrohClientEndpoint
Capability proving an outbound iroh endpoint was constructed by IrohSubstrate::new with the owned PQ-hybrid carrier policy.
RefuseHandler
Fail-closed protocol handler for an ALPN that is intentionally disabled.

Constants§

ALPN_HYPRSTREAM_RPC
ALPN for the raw Cap’n Proto bidi RPC plane.
ALPN_MOQ_LITE
ALPN for moq-net (moq-lite). Must equal moq_net::version::ALPN_LITE.