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.

keyed-tcp is cleartext. noise-tcp seals the same sockets. noise-relay seals the CapTP stream so a relay only forwards ciphertext.

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.