iroh: encrypted peer-to-peer

iroh lets two peers find each other without a fixed address. It carries session bytes over QUIC, whose handshake proves possession of the peer’s key. Discovery, relays, and NAT traversal help peers connect through home routers and firewalls. The CapTP session on top is unchanged. For a direct TCP route between glowcap peers that only needs encryption, use Noise (noise-tcp) instead.

Spritely Goblins ships no iroh netlayer, so glowcap’s live Goblins-over-iroh check (zig build goblins-iroh) uses an adapter in its source tree, under conformance/goblins-peer/. Prefer onion when the other side runs Goblins as it ships.

Dial

You configure the iroh provider (the loaded iroh transport) once, and each dial passes only the locator and any per-connect options.

Zig

const std = @import("std");
const glowcap = @import("glowcap");
const iroh = @import("iroh");

pub fn example(io: std.Io, allocator: std.mem.Allocator, partner_uri: []const u8) !void {
    const partner = try glowcap.ocapn.model.uri.parsePeer(allocator, partner_uri);
    defer glowcap.ocapn.model.freePeerLocator(allocator, partner);
    var endpoint = try iroh.Resident.init(io, null, .{ .reachability = .discovery });
    defer endpoint.deinit() catch |err| std.log.err("iroh endpoint: {s}", .{@errorName(err)});
    var adapter = try iroh.MultiplexedAdapter.init(allocator, &endpoint);
    defer if (adapter.deinit()) |failure| std.log.err("iroh adapter: {s}", .{failure.primaryName()});
    const residents = [_]glowcap.driver.HostRuntime.ProviderRegistration{
        .{ .profile = iroh.transport_profile, .resident = adapter.multiplexed() },
    };

    const session = try glowcap.driver.connect(
        allocator,
        io,
        .{ .residents = &residents },
        partner,
        .ephemeral,
        .{ .handshake = .{ .ms = 10_000 }, .settle = .{ .ms = 10_000 } },
    );

TypeScript

import { Runtime } from "@glowcap/runtime";
import { locator, provider, Reachability } from "@glowcap/iroh";

// Discovery resolves a bare iroh node ID without an address hint.
const nodeId = "<64 lowercase hex characters from the server>";
const partner = locator(nodeId);

await using runtime = await Runtime.open({
	providers: [provider({ reachability: Reachability.Discovery })],
});

Browser

import { init } from "@glowcap/web";

const web = await init({
	wasm: fetch("/glowcap_host.wasm"),
	relayUrl: (locator) => `wss://relay.example/relay?locator=${encodeURIComponent(locator)}`,
});
await using runtime = web.runtime;
// Copy the server's full URI, including direct-addresses reachable from the relay.
const peerUri = "ocapn://<64 lowercase hex characters>.iroh?direct-addresses=127.0.0.1%3A5000";
const partner = web.parseLocator(peerUri);

Python

from glowcap import Runtime
from glowcap.iroh import IrohConfig, Reachability, locator, provider

# DISCOVERY resolves a bare iroh node ID without an address hint.
node_id = "<64 lowercase hex characters from the server>"
partner = locator(node_id)

async with Runtime.open(
    providers=[provider(IrohConfig(Reachability.DISCOVERY))]
) as runtime:

Rust

use glowcap::iroh::{self, Reachability};
use glowcap::{Argument, ConnectOptions, PendingWork, Runtime, RuntimeConfig};

// Discovery resolves a bare iroh node ID without an address hint.
// Cargo.toml: glowcap = { …, features = ["iroh"] }
let node_id = "<64 lowercase hex characters from the server>";
let partner = iroh::locator(node_id, None);

let runtime = Runtime::open(RuntimeConfig::providers([iroh::provider(iroh::Config::new(
    Reachability::Discovery,
))]))
.await?;

Racket

(require glowcap/glowcap
         glowcap/glowcap-iroh)

;; IROH-REACH-DISCOVERY resolves a bare iroh node ID without an address hint.
(define node-id "<64 lowercase hex characters from the server>")
(define partner (iroh-locator node-id))

(define runtime
  (open-runtime
   #:providers (list (iroh-provider (make-iroh-config IROH-REACH-DISCOVERY)))))

Listen

Listening binds the provider’s node identity and returns the locator partners can use.

Zig

const std = @import("std");
const glowcap = @import("glowcap");
const iroh = @import("iroh");

pub fn example(io: std.Io, allocator: std.mem.Allocator) !void {
    var seed: [32]u8 = undefined;
    try io.randomSecure(&seed); // retain this seed to restore the node identity
    const secret = glowcap.foundation.crypto.SecretKey.fromSeed(seed);
    var endpoint = try iroh.Resident.init(io, &seed, .{ .reachability = .discovery });
    defer endpoint.deinit() catch |err| std.log.err("iroh endpoint: {s}", .{@errorName(err)});
    var adapter = try iroh.MultiplexedAdapter.init(allocator, &endpoint);
    defer if (adapter.deinit()) |failure| std.log.err("iroh adapter: {s}", .{failure.primaryName()});
    const residents = [_]glowcap.driver.HostRuntime.ProviderRegistration{
        .{ .profile = iroh.transport_profile, .resident = adapter.multiplexed() },
    };
    const server = try glowcap.driver.listen(
        allocator,
        io,
        .{ .residents = &residents },
        iroh.transport_name,
        .{ .designator = "" },
        .{ .keyed = secret },
        .{ .handshake = .{ .ms = 10_000 }, .settle = .{ .ms = 10_000 } },
    );
    defer server.deinit();

    const uri = try glowcap.ocapn.model.uri.writePeer(allocator, (try server.advertisedLocator()));
    defer allocator.free(uri);
    std.debug.print("{s}\n", .{uri}); // hand this locator to partners

    try serve(server);
}

TypeScript

import type { Argument } from "@glowcap/runtime";
import { type IrohConfig, listen, Reachability } from "@glowcap/iroh";

// This listener is named by its node id. Partners can dial it from anywhere.
const config: IrohConfig = { reachability: Reachability.Discovery };
await using server = await listen(config);

Python

from glowcap import Argument
from glowcap.iroh import IrohConfig, Reachability, listen

# This listener is named by its node id. Partners can dial it from anywhere.
async with await listen(IrohConfig(Reachability.DISCOVERY)) as server:

Rust

use glowcap::iroh::{self, Reachability};
use glowcap::Argument;

// This listener is named by its node id. Partners can dial it from anywhere.
// Cargo.toml: glowcap = { …, features = ["iroh"] }
let server = iroh::listen(
    iroh::Config::new(Reachability::Discovery),
    iroh::ListenOptions::default(),
)
.await?;

Racket

(require glowcap/glowcap
         glowcap/glowcap-iroh)

;; This listener is named by its node id. Partners can dial it from anywhere.
(define server (listen-iroh (make-iroh-config IROH-REACH-DISCOVERY)))
(printf "~a\n" (iroh-server-uri server)) ; hand this locator to partners
(define host (iroh-server-host server))
(define (accept-session) (iroh-server-accept server))

The durable key and session key have separate jobs

Each endpoint has a durable Ed25519 keypair. Its public key has two roles:

  • It is the iroh node id the transport authenticates the QUIC channel against.
  • It is the designator, the peer’s name inside an OCapN locator, the part you dial in an ocapn://<node-id>.iroh URI.

Every CapTP session also draws a fresh signing key. The hello signature proves control of that session key and binds it to the locator the partner claims. It does not prove control of the durable node id. The iroh channel proves that, and glowcap requires the hello’s claimed designator to match the id the channel authenticated.

Binding from the same seed restores the node identity at a new network address. A sturdyref works after that restart only if the application also restores the named object under the same swiss number (the secret name a sturdyref carries).

Reaching a peer

A peer hands you its node id. You choose how that id becomes a route when you bind the endpoint:

ModeHow a dial resolves
directLocator hints carry the peer’s socket addresses
local_discoveryAn in-process address book resolves the id
discoveryPublic relays run by n0 (the company behind iroh) and DNS/pkarr resolve the id
discovery_no_relayDNS/pkarr resolves published addresses with relay fallback disabled

direct and local_discovery are deterministic. discovery publishes node information and depends on public infrastructure and propagation. The no-relay form needs a publicly reachable direct address.

Optional Rust library

iroh’s QUIC stack is Rust, so glowcap ships it as a separate library, libglowcap_net_transport_iroh (ADR-0021). The base archives stay pure Zig, and building this one requires cargo. Every language keeps it optional:

  • A Zig build enables .iroh = true in its dependency options, then imports glowcap.module("glowcap_iroh"), which links the Rust library. A program that never imports it never runs cargo.
  • Each binding keeps iroh in its own module: the @glowcap/iroh package, glowcap.iroh, glowcap-iroh.rkt, and Rust’s opt-in iroh feature.
  • A program loads it only by installing the iroh provider, so one that speaks only TCP never does. Rust compiles it in behind the feature instead.

Scale: many connections, one thread

A session from connect runs its own runtime on the calling thread. To serve many sessions from one thread, a Host watches one descriptor that signals when any iroh connection is ready (ADR-0019). Performance measures both paths. iroh’s own memory is not part of glowcap’s core session footprint.

Three-party handoff over iroh

A handoff over iroh works as on any session: the introducer names the object’s host by node id, and the recipient dials that id on a fresh encrypted session to collect it.

For a full application, run the Rooms chat with zig build demo-rooms-iroh.