Onion: the standardized OCapN transport
An onion service carries a glowcap session over Tor. A peer is named by a version 3 service id, the 56 base32 characters in ocapn://<serviceid>.onion. Bytes travel a Tor circuit: encrypted, with both ends’ network location hidden.
This is the only transport the OCapN draft standardizes, and the only netlayer upstream Spritely Goblins ships. Every other live Goblins check (cleartext tcp, and iroh) runs over an adapter glowcap provides. Over Tor, each side uses its own implementation of the draft transport, and zig build goblins-onion is the live check.
A Tor you already run
glowcap talks to a Tor daemon you run. Give the netlayer two endpoints. Each is a host:port, or in a binding, an absolute Unix socket path:
- the SOCKS endpoint, which glowcap dials through, and
- the control endpoint, which glowcap asks for a service when it hosts.
Without the control endpoint, the netlayer can dial but cannot host. To authenticate to the control endpoint, glowcap sends a cookie file’s bytes or a password.
Hosting creates a version 3 onion service and reports the service id partners dial, plus the key that restores that address after a restart. Store the key and pass it back to keep one address across restarts.
Dial
Point the netlayer at an already-running Tor SOCKS endpoint and name the service id to reach.
Zig
const std = @import("std");
const glowcap = @import("glowcap");
pub fn example(io: std.Io, allocator: std.mem.Allocator) !void {
// Dial through a running Tor daemon's SOCKS port.
const transports: glowcap.driver.Transports = .{ .symbols = &.{.onion}, .onion = .{
.socks = try glowcap.net.tcp.parseDesignator("127.0.0.1:9050"),
} };
const partner = glowcap.net.onion.locator("<56-character onion service id>");
const session = try glowcap.driver.connect(
allocator,
io,
transports,
partner,
.ephemeral,
.{ .handshake = .{ .ms = 10_000 }, .settle = .{ .ms = 10_000 } },
);
TypeScript
import { locator, provider } from "@glowcap/onion";
import { Runtime } from "@glowcap/runtime";
// glowcap starts no Tor; point the provider at an existing SOCKS endpoint.
const partner = locator("<56-character onion service id>");
await using runtime = await Runtime.open({
providers: [provider({ socks: "/run/tor/socks" })],
});
Python
from glowcap import Runtime, onion
# glowcap starts no Tor; point the provider at an existing SOCKS endpoint.
partner = onion.locator("<56-character onion service id>")
async with Runtime.open(
providers=[onion.provider(onion.OnionConfig(socks="/run/tor/socks"))]
) as runtime:
Rust
use glowcap::onion::{self, Config};
use glowcap::{Argument, ConnectOptions, PendingWork, Runtime, RuntimeConfig};
// glowcap starts no Tor; point the provider at an existing SOCKS endpoint.
let partner = onion::locator("<56-character onion service id>");
let runtime = Runtime::open(RuntimeConfig::providers([onion::provider(
Config::dial_only("/run/tor/socks"),
)]))
.await?;
Racket
(require glowcap/glowcap glowcap/glowcap-onion)
;; glowcap starts no Tor; point the provider at an existing SOCKS endpoint.
(define partner (onion-locator "<56-character onion service id>"))
(define runtime
(open-runtime #:providers
(list (onion-provider #:socks "/run/tor/socks"))))
Listen
Listening asks your Tor daemon to create the onion service and returns the locator partners dial. The session is the same CapTP Session as on every other transport. A program that moves frames itself can use the raw onion Netlayer the bindings expose.
Zig
const std = @import("std");
const glowcap = @import("glowcap");
pub fn example(io: std.Io, allocator: std.mem.Allocator) !void {
// glowcap starts no Tor. Name an already-running daemon's SOCKS and control ports.
const server = try glowcap.driver.listen(
allocator,
io,
.{ .symbols = &.{.onion}, .onion = .{
.socks = try glowcap.net.tcp.parseDesignator("127.0.0.1:9050"),
.control = try glowcap.net.tcp.parseDesignator("127.0.0.1:9051"),
} },
glowcap.ocapn.model.transport.onion,
.{ .designator = "" },
.ephemeral,
.{ .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
var service_key_storage: [256]u8 = undefined;
const key_len = (try server.restorationState(&service_key_storage)) orelse
return error.RestorationStateUnavailable;
const service_key = service_key_storage[0..key_len];
_ = service_key; // persist securely to restore this service
try serve(server);
}
TypeScript
import type { Argument } from "@glowcap/runtime";
import { listen } from "@glowcap/onion";
// glowcap starts no Tor. Name an already-running daemon's SOCKS (and control to host).
await using server = await listen({
socks: "/run/tor/socks",
control: "/run/tor/control",
});
const _serviceKey = server.serviceKey; // persist securely to restore this service
Python
from glowcap import Argument, onion
# glowcap starts no Tor. Name an already-running daemon's SOCKS (and control to host).
async with await onion.listen("/run/tor/socks", control="/run/tor/control") as server:
service_key = server.service_key # persist securely to restore this service
Rust
use glowcap::onion::{self, Auth, Config};
use glowcap::Argument;
// glowcap starts no Tor. Name an already-running daemon's SOCKS (and control to host).
let config = Config::dial_only("/run/tor/socks")
.with_control("/run/tor/control", Auth::None);
let server = onion::listen(config, onion::ListenOptions::default()).await?;
let service_key = server.service_key(); // persist securely to restore this service
Racket
(require glowcap/glowcap glowcap/glowcap-onion)
;; glowcap starts no Tor. Name an already-running daemon's SOCKS (and control to host).
(define server (listen-onion #:socks "/run/tor/socks"
#:control "/run/tor/control"))
(printf "~a\n" (onion-server-uri server)) ; hand this locator to partners
(define service-key (onion-server-service-key server)) ; persist securely
(define host (onion-server-host server))
(define (accept-session) (onion-server-accept server))
What Tor proves
Tor proves the far end of the circuit holds the key the address encodes, so the bytes reached the service you meant. It does not say who the CapTP peer is: the peer is whoever holds the local socket that service forwards to.
The accepting side learns nothing about who dialed it. CapTP does not need to know, because what a caller may do depends on the references it holds, not on who it is.
A three-party handoff is the exception. It relies on the location a peer declared, and an accepted circuit has nothing to check that declaration against, so glowcap reports it as unproven. An iroh session can report a proved peer, because QUIC authenticated the node id.
Bare onion locators
The service id already says where to dial, so glowcap sends onion locators without hints. When introducing an object to a peer known to run glowcap, it keeps the hints. The Goblins release glowcap pins cannot dial an onion locator that carries hints, even though the OCapN locator rules say hints never change which peer an address names. Hints on a locator glowcap receives are ignored rather than refused.
The hello can still carry hints, which is how a peer states a preferred wire profile. Live Goblins accepts a hinted hello and ignores the hints (zig build goblins-onion checks this every run), so two glowcap peers over Tor can agree on glowcap-next, glowcap’s own experimental CapTP version. The dialer asks for it when it was handed the glowcap form of the address, and an acceptor configured for it answers the same way. Every other session, including every session with a Goblins vat, uses the baseline. ADR-0042 records the locator rule and how a dialer picks glowcap’s own profile only when it knows the other side is glowcap.
Choosing a transport compares onion with the other transports.