Go

The Go module github.com/syalia-srl/relay/go, package relay, implements both ends of the channel protocol: the host of a server install and the guest of a client. It pairs two static keys through a relay, then carries messages with Noise IKpsk1 and KK (PROTOCOL.md sections 3 to 9). A message is a []byte; one Send arrives as one Recv, up to the 16 MiB limit of the protocol. Every call that waits takes a context.Context; every call that can fail returns an error. The API has no goroutines or channels of its own.

The public surface is four things: a host, a guest, a pairing, and a peer to send to and receive from. The only dependency is github.com/coder/websocket; the cryptography is in the standard library (crypto/ecdh, crypto/aes, crypto/cipher, crypto/hkdf, crypto/hmac, crypto/sha256).

Install¶

go get github.com/syalia-srl/relay/go

The module requires Go 1.27 or later.

A host¶

relay.OpenHost reads or creates the state through a store, draws the host's static key on the first run, and opens a socket on every channel of every bound device:

host, err := relay.OpenHost(ctx, relay.FileStore("state/host"), []relay.Relay{
    {
        URL:     "wss://relay.example.com", // the guests' URL
        HostURL: "ws://127.0.0.1:8010",     // the host's own URL
        Key:     projectKey,
    },
})
if err != nil { ... }
defer host.Close()

The relay list is ordered. The host creates a pairing channel, and later one device channel, on each relay, and keeps a socket on each. A relay.Relay has two URLs. URL is the guests' URL: it passes the policy of section 8.1 (wss, or ws to a literal private address), it is the only relay URL in pairing payloads and relays messages, and it carries the traffic between the two sides. HostURL is optional and defaults to URL; the host uses it for its own HTTP calls and sockets. A ws:// host URL sends the project key and the host token in cleartext, so it is safe only on loopback or on a network whose only members are the host and the relay, such as a container network; the library cannot check that. The example runs the host on the relay's machine, so the host dials loopback and guests use the public wss:// URL.

host.Pair(ctx, name) draws a device id, a pairing secret and the channels:

pairing, err := host.Pair(ctx, "pixel-7")
showQR(pairing.Payload())                        // string, the JSON of section 4

Payload() is the pairing payload. The application renders it as a QR code or as copied text with any library it likes; the relay library does not draw it. The payload carries the pairing secret and live guest tokens, so it travels only over the application's authenticated admin connection and is never logged.

The host confirms in a later request, after a person reads the six digits on the guest. The device id is what the admin session stores between the two requests:

pairing, err := host.Pairing(deviceID)           // the id from pairing.Device()
device, err := pairing.Confirm(ctx, code)        // *relay.WrongCodeError, relay.ErrPairingFailed

host.Pairing(id) returns the open pairing or an error when it has ended. Confirm is the only way to bind a key. A wrong code returns a *relay.WrongCodeError with TriesLeft; the third wrong code, two pending keys with the same code, the expiry or the 10-minute limit return an error that errors.Is(err, relay.ErrPairingFailed). The host never exposes the codes of pending keys.

Messages from every bound device arrive through host.Recv:

for {
    device, message, err := host.Recv(ctx)
    if err != nil { break }                      // relay.ErrClosed after Close
    err = device.Send(ctx, message)              // echo it back
}

device.Send waits until the device is connected or ctx ends. host.Devices() lists the bound devices, each with ID(), Name() and Connected(). Revocation sends revoked, deletes the channels on every relay and unbinds the key:

err = host.Revoke(ctx, device)

Every method is safe to call from several goroutines. host.Close() stops the sockets; the bound devices and their channels stay in the store.

A guest¶

relay.OpenGuest reads or creates the guest state. Its third argument is nil, which makes the library draw a fresh static key for each pairing and keep it in the store:

guest, err := relay.OpenGuest(ctx, relay.FileStore("state/guest"), nil)
defer guest.Close()

A native key store implements relay.StaticKey:

type StaticKey interface {
    PublicKey() []byte
    DH(peerPublic []byte) ([]byte, error)
}

The library asks that object for Diffie-Hellman results and never sees the private key, so the key can live in an HSM or another process. A native key serves one pairing: a second host needs a second Guest with its own store and key.

First contact takes the payload string and returns the paired host:

link, err := guest.Pair(ctx, pairing.Payload())  // relay.ErrPayloadInvalid on a bad payload
fmt.Println(link.Code())                         // the 6 digits the person types
if err := link.Bound(ctx); err != nil { ... }    // device channels carry a session

guest.Pair returns once the host holds the guest's key candidate and the pairing code exists, which is before the person has typed it. link.Bound(ctx) returns when the host has confirmed and the device channels work.

err = link.Send(ctx, message)
message, err := link.Recv(ctx)                   // relay.ErrRevoked when revoked

Recv returns relay.ErrRevoked when the host revokes the device. Unpairing sends close, waits for closed and forgets the host; guest.Close() only stops the connections and keeps the pairings in the store:

err = link.Unpair(ctx)
err = guest.Close()

After a restart, guest.Hosts() lists the paired hosts. A pairing that a restart interrupts is not kept: the person scans a new payload.

Three rounds in which every relay answers 4401 or 4410 make the guest treat the pairing as revoked: it deletes the pairing from its store, and guest.Hosts() no longer lists it. A relay that lost its channel store, or that swept a channel with no socket for 30 days, causes the same. The person then scans a new payload.

Store¶

type Store interface {
    Load() ([]byte, error)   // nil, nil on the first run
    Save([]byte) error
}

relay.FileStore(path) writes atomically at mode 0600. An application can keep the same bytes in a database or in a secret manager behind its own Store. The state holds keys: the host's static key, or the guest's per-pairing keys.

Errors¶

errors.Is and errors.As match all of them. Transient network errors are retried inside the library and never returned.

What the application still owns¶

PROTOCOL.md section 10 lists five duties outside the encrypted stream. The library's shape leaves them where they belong:

The application also owns the QR display, the admin login that carries the payload and the code, and the choice of relays.

Worked example¶

The example is one program with an echo host and a guest in the same process. It starts both from temporary stores, pairs them through a relay, sends one message from the guest, echoes it from the host and prints the reply. The person's step is played by the program: pairing.Confirm(ctx, link.Code()) uses the code the guest shows, where a real application would read it from a person.

// An echo host and a guest that pair through a relay and exchange one message.
//
//  RELAY_URL=ws://10.255.0.1:8010 RELAY_KEY=<project key> \
//      go run ./examples/echo
package main

import (
    "context"
    "fmt"
    "log"
    "os"
    "path/filepath"
    "time"

    relay "github.com/syalia-srl/relay/go"
)

func must[T any](value T, err error) T {
    if err != nil {
        log.Fatal(err)
    }
    return value
}

func check(err error) {
    if err != nil {
        log.Fatal(err)
    }
}

func main() {
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()
    dir := must(os.MkdirTemp("", "relay-example-"))
    defer os.RemoveAll(dir)
    url := os.Getenv("RELAY_URL")
    if url == "" {
        url = "ws://10.255.0.1:8010"
    }
    host := must(relay.OpenHost(ctx, relay.FileStore(filepath.Join(dir, "host")),
        []relay.Relay{{URL: url, Key: os.Getenv("RELAY_KEY")}}))
    defer host.Close()
    guest := must(relay.OpenGuest(ctx, relay.FileStore(filepath.Join(dir, "guest")), nil))
    defer guest.Close()

    pairing := must(host.Pair(ctx, "echo"))
    link := must(guest.Pair(ctx, pairing.Payload()))
    // A person reads link.Code() on the guest and types it into the host.
    _ = must(pairing.Confirm(ctx, link.Code()))
    check(link.Bound(ctx))

    go func() {
        for {
            device, message, err := host.Recv(ctx)
            if err != nil {
                return
            }
            if device.Send(ctx, message) != nil {
                return
            }
        }
    }()

    check(link.Send(ctx, []byte("hello from the guest")))
    reply := must(link.Recv(ctx))
    fmt.Printf("guest received: %q\n", reply)
    check(link.Unpair(ctx))
}

It runs against a relay on a private address, because a guest accepts ws:// only to one (section 8.1):

RELAY_URL=ws://10.255.0.1:8010 RELAY_KEY=<project key> \
    go run ./examples/echo

The command runs from the go/ directory and prints one line, guest received: "hello from the guest". The relay page covers the relay, its keys file and its checks.