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 globalmoq_stream::Originfor the streaming plane.ALPN_HYPRSTREAM_RPC(hyprstream-rpc/1) — raw Cap’n Proto bidi handler, wired by the daemon spawner (#282) to terminateIrohRpcProtocolHandlerfor 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§
- Echo
Handler - 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.
- Iroh
Substrate - Two-plane iroh substrate: one shared QUIC endpoint, two ALPN-dispatched protocol handlers.
- Noop
Handler - Placeholder protocol handler that accepts an incoming connection and immediately returns. Used until Phase 2 / Phase 3 wire the real handlers.
- Owned
Iroh Client Endpoint - Capability proving an outbound iroh endpoint was constructed by
IrohSubstrate::newwith the owned PQ-hybrid carrier policy. - Refuse
Handler - 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.