Relay Address and keypair

This page states the relay’s identity in the Developer Preview as trueseal-relay ADR-0012 decides it, and the Relay Address as trueseal-sync ADR-0028 decides it.

Keypair

• One long-term X25519 keypair. The private key is stored hex-encoded.
• On first start the container generates /data/keypair.hex (mode 0600) and prints the public key.
• docker compose exec relay trueseal-relay pubkey prints the hex public key.
• TRUESEAL_RELAY_KEYPAIR_HEX supplies an Operator’s own private key. The entrypoint writes it to the keypair path instead of generating one.
• Devices verify the relay’s static key in every handshake: Noise XX on Receive Sessions, Noise NK on Push Sessions (trueseal-relay ADR-0002).

Relay Address

trueseal://<relay public key hex>@host[:receivePort][?push=pushPort]

• The receive port defaults to 7700 and the push port to 7701.
• The typed form is RelayAddress(host, publicKey, receivePort, pushPort). open() accepts either form.
• invalidRelayAddress is the error case for a malformed Relay Address.
• A port is never dropped silently.
• The relay CLI prints the Relay Address.
• Distribution to apps is out of band, for example a build-time constant (trueseal-relay ADR-0004).

Rotation

• The preview does not support rotating the relay key.
• Changing the key breaks every client configured with the old Relay Address.
• Recovery from a changed or lost key is a new Relay Address shipped in a new app release.

A leaked private key

An attacker holding the private key can impersonate the relay to devices that reach the attacker. Its effect on each property:

Operator’s job

• Getting the Relay Address to the app developer.
• Backing up keypair.hex once and keeping it private.
• Never replacing the key on a relay devices depend on.