Noise: sealed channels on TCP and the relay
noise-tcp seals a CapTP session between two glowcap peers over ordinary TCP. Before any CapTP byte moves, the peers run a Noise_XK handshake, and after that they exchange only encrypted records. Completing the handshake proves the far end holds the dialed durable key. A replayed handshake is refused. keyed-tcp uses the same designator but leaves CapTP frames in the clear. ADR-0041 explains the design.
Spritely Goblins ships no Noise netlayer, so these transports connect glowcap to glowcap. To connect to Goblins, use onion, iroh with glowcap’s Goblins adapter, or cleartext tcp for testing. Prefer noise-tcp when two glowcap peers already share a TCP route and only need the stream sealed, and iroh when they also need discovery or NAT traversal. Choosing a transport compares them all.
Dial
TCP
Zig
const std = @import("std");
const glowcap = @import("glowcap");
pub fn example(io: std.Io, allocator: std.mem.Allocator) !void {
// Same TCP sockets as cleartext keyed dialing; Noise_XK seals the CapTP stream.
// The designator is the peer's durable key; the hint is where to dial.
var hint_storage: [1]glowcap.ocapn.model.HintEntry = undefined;
const peer_key = "<64 lowercase hex characters from the server>";
const partner = glowcap.net.tcp.noise.locator(
peer_key,
"127.0.0.1:9099",
&hint_storage,
);
const session = try glowcap.driver.connect(
allocator,
io,
.{ .symbols = &.{.noise_tcp} },
partner,
.ephemeral,
.{ .handshake = .{ .ms = 10_000 }, .settle = .{ .ms = 10_000 } },
);
TypeScript
import { noise, provider } from "@glowcap/tcp";
import { Runtime } from "@glowcap/runtime";
// Same TCP sockets as keyed dialing; Noise_XK seals the CapTP stream.
const peerKey = "<64 lowercase hex characters from the server>";
const partner = noise.locator(peerKey, "127.0.0.1", 9099);
await using runtime = await Runtime.open({ providers: [provider()] });
Python
from glowcap import Runtime, tcp
# Same TCP sockets as keyed dialing; Noise_XK seals the CapTP stream.
peer_key = "<64 lowercase hex characters from the server>"
partner = tcp.noise.locator(peer_key, "127.0.0.1", 9099)
async with Runtime.open(providers=[tcp.provider()]) as runtime:
Rust
use glowcap::{tcp, Argument, ConnectOptions, PendingWork, Runtime, RuntimeConfig};
// Same TCP sockets as keyed dialing; Noise_XK seals the CapTP stream.
let peer_key = "<64 lowercase hex characters from the server>";
let partner = tcp::noise::locator(peer_key, "127.0.0.1", 9099);
let runtime = Runtime::open(RuntimeConfig::providers([tcp::provider(tcp::Config::default())])).await?;
Racket
(require glowcap/glowcap glowcap/glowcap-tcp)
;; Same TCP sockets as keyed dialing; Noise_XK seals the CapTP stream.
(define peer-key "<64 lowercase hex characters from the server>")
(define partner (noise-tcp-locator peer-key "127.0.0.1" 9099))
(define runtime (open-runtime #:providers (list (tcp-provider))))
Relay
Zig
const std = @import("std");
const glowcap = @import("glowcap");
const relay_tls = @import("relay_tls");
pub fn example(io: std.Io, allocator: std.mem.Allocator) !void {
// Noise_XK seals the session end to end; the relay forwards ciphertext.
const relay_url = "wss://relay.example/relay";
var tls = switch (relay_tls.initTlsOwner(io, allocator, .system)) {
.ready => |ready| ready.owner,
.failed => return error.RelayUnavailable,
};
defer switch (tls.release()) {
.released => {},
.busy, .failed => std.log.err("relay TLS teardown failed", .{}),
};
var entropy: [std.Random.DefaultCsprng.secret_seed_length]u8 = undefined;
try io.randomSecure(&entropy);
const transports: glowcap.driver.Transports = .{ .symbols = &.{.noise_relay}, .relay = .{
.url = relay_url,
.entropy_seed = entropy,
.resolver_io = io,
.tls_owner = tls,
} };
var hint_storage: [1]glowcap.ocapn.model.HintEntry = undefined;
const peer_key = "<64 lowercase hex characters from the server>";
const partner = glowcap.net.relay.noise.locator(peer_key, relay_url, &hint_storage);
const session = try glowcap.driver.connect(
allocator,
io,
transports,
partner,
.ephemeral,
.{ .handshake = .{ .ms = 10_000 }, .settle = .{ .ms = 10_000 } },
);
TypeScript
import { Runtime } from "@glowcap/runtime";
import { noise, provider } from "@glowcap/relay";
// Noise_XK seals the session end to end; the relay forwards ciphertext.
const peerKey = "<64 lowercase hex characters from the server>";
const relayUrl = "wss://relay.example/relay";
const partner = noise.locator(peerKey, relayUrl);
await using runtime = await Runtime.open({
providers: [provider({ relayUrl })],
});
Browser
import { connector, noise } from "@glowcap/relay";
import { init } from "@glowcap/web";
const relayUrl = "wss://relay.example/relay";
const web = await init({
wasm: fetch("/glowcap_host.wasm"),
connectors: [connector()],
});
await using runtime = web.runtime;
const partner = noise.locator("<64 lowercase hex characters>", relayUrl);
Python
from glowcap import Runtime, relay
# Noise_XK seals the CapTP stream end to end through the relay.
peer_key = "<64 lowercase hex characters from the server>"
relay_url = "wss://relay.example/relay"
partner = relay.noise.locator(peer_key, relay_url)
async with Runtime.open(providers=[relay.provider(relay_url)]) as runtime:
Rust
use glowcap::{relay, Argument, ConnectOptions, PendingWork, Runtime, RuntimeConfig};
// Noise_XK seals the CapTP stream end to end through the relay.
let peer_key = "<64 lowercase hex characters from the server>";
let relay_url = "wss://relay.example/relay";
let partner = relay::noise::locator(peer_key, relay_url);
let runtime = Runtime::open(RuntimeConfig::providers([relay::provider(
relay::Config::dial_only(relay_url),
)]))
.await?;
Racket
(require glowcap/glowcap glowcap/glowcap-relay)
;; Noise_XK seals the CapTP stream end to end through the relay.
(define peer-key "<64 lowercase hex characters from the server>")
(define relay-url "wss://relay.example/relay")
(define partner (noise-relay-locator peer-key relay-url))
(define runtime
(open-runtime #:providers (list (relay-provider #:relay-url relay-url))))
Listen
Each tab shows a binding that supports listening on this transport. Listening on the relay means registering: the peer publishes its key at the relay and waits there.
TCP
Zig
const std = @import("std");
const glowcap = @import("glowcap");
pub fn example(io: std.Io, allocator: std.mem.Allocator) !void {
const seed = @as([32]u8, @splat(7)); // load durable secret bytes in a real service
const secret = glowcap.foundation.crypto.SecretKey.fromSeed(seed);
const server = try glowcap.driver.listen(
allocator,
io,
.{ .symbols = &.{.noise_tcp} },
glowcap.ocapn.model.transport.noise_tcp,
.{ .designator = "127.0.0.1:9099" },
.{ .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}); // Noise proves this durable key to dialers
try serve(server);
}
TypeScript
import type { Argument } from "@glowcap/runtime";
import { noise } from "@glowcap/tcp";
// Same bind as keyed-tcp; Noise_XK seals every accepted CapTP stream.
const seed = crypto.getRandomValues(new Uint8Array(32));
await using server = await noise.listen("127.0.0.1", 9099, { seed });
Python
import os
from glowcap import Argument, tcp
# Same bind as keyed-tcp; Noise_XK seals every accepted CapTP stream.
# Persist the 32-byte seed to keep the same key.
seed = os.urandom(32)
async with await tcp.noise.listen("127.0.0.1", 9099, seed=seed) as server:
Rust
use glowcap::{tcp, Argument};
// Same bind as keyed-tcp; Noise_XK seals every accepted CapTP stream.
let seed = [7u8; 32]; // replace with durable secret bytes across restarts
let server = tcp::noise::listen(
"127.0.0.1",
9099,
tcp::ListenOptions {
identity: tcp::ListenerIdentity::Seed(seed),
..tcp::ListenOptions::default()
},
)
.await?;
Racket
(require glowcap/glowcap
glowcap/glowcap-tcp)
;; Same bind as keyed-tcp; Noise_XK seals every accepted CapTP stream.
(define seed (make-bytes 32 7)) ; Replace with durable secret bytes.
(define server (listen-noise-tcp "127.0.0.1" 9099 #:seed seed))
(printf "~a\n" (server-uri server)) ; hand this locator to partners
(define host (server-host server))
(define (accept-session) (accept server))
Relay
Zig
const std = @import("std");
const glowcap = @import("glowcap");
const relay_tls = @import("relay_tls");
pub fn example(io: std.Io, allocator: std.mem.Allocator) !void {
// Register this key at the relay; Noise_XK seals every accepted CapTP stream.
const seed = @as([32]u8, @splat(7)); // load durable secret bytes in a real service
const secret = glowcap.foundation.crypto.SecretKey.fromSeed(seed);
var tls = switch (relay_tls.initTlsOwner(io, allocator, .system)) {
.ready => |ready| ready.owner,
.failed => return error.RelayUnavailable,
};
defer switch (tls.release()) {
.released => {},
.busy, .failed => std.log.err("relay TLS teardown failed", .{}),
};
var entropy: [std.Random.DefaultCsprng.secret_seed_length]u8 = undefined;
try io.randomSecure(&entropy);
const server = try glowcap.driver.listen(
allocator,
io,
.{ .symbols = &.{.noise_relay}, .relay = .{
.url = "wss://relay.example/relay",
.entropy_seed = entropy,
.resolver_io = io,
.tls_owner = tls,
.registration = .{ .url = "wss://relay.example/register" },
} },
glowcap.ocapn.model.transport.noise_relay,
.{ .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}); // Noise seals the relay path end to end
try serve(server);
}
TypeScript
import type { Argument } from "@glowcap/runtime";
import { noise } from "@glowcap/relay";
// Register this key at the relay; Noise_XK seals every accepted CapTP stream.
const seed = crypto.getRandomValues(new Uint8Array(32));
await using server = await noise.listen({
relayUrl: "wss://relay.example/relay",
registerUrl: "wss://relay.example/register",
seed,
});
Python
import os
from glowcap import Argument, relay
# Register this key at the relay; Noise_XK seals every accepted CapTP stream.
seed = os.urandom(32) # load durable secret bytes in a real service
async with await relay.noise.listen(
"wss://relay.example/relay",
"wss://relay.example/register",
seed=seed,
) as server:
Rust
use glowcap::{relay, Argument};
// Register this key at the relay; Noise_XK seals every accepted CapTP stream.
let seed = [7u8; 32]; // replace with durable secret bytes across restarts
let server = relay::noise::listen(
"wss://relay.example/relay",
"wss://relay.example/register",
relay::ListenOptions {
identity: relay::ListenerIdentity::Seed(seed),
..relay::ListenOptions::default()
},
)
.await?;
Racket
(require glowcap/glowcap
glowcap/glowcap-relay)
;; Register this key at the relay; Noise_XK seals every accepted CapTP stream.
(define seed (make-bytes 32 7)) ; Replace with durable secret bytes.
(define server (listen-noise-relay
"wss://relay.example/relay"
"wss://relay.example/register"
#:seed seed))
(printf "~a\n" (server-uri server)) ; hand this locator to partners
(define host (server-host server))
(define (accept-session) (accept server))
Transport details
The designator is the peer’s durable public key, and the bound address rides in the direct-addresses hint:
ocapn://<64 hex chars>.noise-tcp?direct-addresses=127.0.0.1%3A9099
A listener binds a durable key, and the advertised locator is what partners dial. The C driver loop and the Rust, Python, TypeScript, and Racket bindings dial and listen through the TCP provider package, which owns noise-tcp, keyed-tcp, and testing tcp together.
Through the relay
noise-relay is the same sealed channel over the relay pipe that keyed-relay uses. The CapTP peers still handshake with each other, and the relay only moves opaque records.
The Rust, Python, TypeScript, and Racket bindings dial and register through the relay provider package. A browser peer speaks the same noise-relay through its WebSocket connector. Rooms can carry direct messages over it through the room’s own relay instead of a WebRTC channel.