Module relay 

Daemon-side relay bridge (runtime-owned).

Holds one persistent outer TLS + WebSocket control connection to a nominated relay, proves the daemon’s Ed25519 registration identity over a signed challenge, and claims a node_id. The relay then multiplexes client connections to the daemon over that single link by conn_id: on each Open the bridge dials the daemon’s own loopback WSS listener and shuttles binary DATA both ways. Those DATA payloads are the inner client<->daemon mTLS, which terminates at the loopback listener exactly as on the direct path; the bridge and the relay only move ciphertext.

WS keepalive pings (below NAT idle windows) detect a half-open link and force a reconnect; reconnects use capped exponential backoff. Cancellation stops the bridge promptly.

Structs

RelayBridgeConfig

Everything the bridge needs to register with, and verify, a relay.

Constants

MAX_NODE_ID_LEN

The node-id rule a relay enforces at registration, for callers that persist a node-id (such as relay claim) and must not save one the relay refuses. Longest node-id a relay registers, in bytes.

Functions

ensure_node_id

Resolve this daemon’s relay node-id.

ensure_signing_key

is_valid_node_id

The node-id rule a relay enforces at registration, for callers that persist a node-id (such as relay claim) and must not save one the relay refuses. Whether node_id is a routing label a relay will register: non-empty, at most MAX_NODE_ID_LEN bytes, and printable ASCII without spaces.

mint_node_id

Mint a fresh, unguessable 128-bit node-id (hex). Decoupled from the cert so a relay compromise leaks only a routing handle, and rotatable without reissuing certs.

persist_node_id

Atomically persist the effective node-id to <data_dir>/relay/node_id (temp + rename), so a concurrent reader (ensure_node_id / relay_profile) never sees a half-written value. This is what makes a rotated id flow to clients in-band on their next renewal.

persist_relay_pin

Persist the relay outer-leaf pin (sha256 hex) atomically at 0600.

relay_pin_path

The relay outer-leaf pin store (<data_dir>/relay/relay_pin). Once recorded (explicitly or by TOFU) the bridge pins the relay’s outer cert, AND enrollment delivers this value to clients so they pin the same leaf (R-E contract).

relay_server_name

Parse relay_host the way the connection path consumes it: as the outer TLS server name, and as the host of the wss:// registration URI.

request_node_id_rotation

Request an on-demand node-id rotation by touching the trigger file. The running daemon’s bridge picks it up within its poll interval (auto-mint mode only).

rotate_trigger_path

The on-demand rotation trigger file. zeroclaw security relay-rotate-node-id touches it; the running bridge polls for it and rotates when it appears.

run_relay_bridge

Run the relay bridge until cancel fires.