Security Model

What a paired device can do

A paired device can do anything with your Rex server that you can. Rex sees every forwarded connection as coming from the user running serve, which is you. So a paired device can open terminals and run commands as your user on the issuer.

Treat pairing like adding an SSH key to authorized_keys. Pair devices you control, and revoke them when you stop using them or lose them.

Pairing only goes one way: the joiner gets access to the issuer, and the issuer gets nothing on the joiner. The devices that can connect to you are exactly the ones rex-iroh peers list shows.

Identity

Each device has a key pair, kept in secret.key in its state directory. The public key is the device’s endpoint id, and the endpoint id is the only thing rex-iroh treats as identity. When a device connects, iroh proves which key it holds during the connection handshake, and the issuer checks that key against its allowlist.

Everything else a device says about itself is display text. Labels are chosen by the joiner and can say anything, which is why the pairing prompt shows the start of the endpoint id and the five words next to the label.

Pairing

An invite contains the issuer’s ticket, which says how to reach it, and a random 32-byte secret. The issuer accepts the secret once, within 120 seconds of creating it. After that, the invite is useless.

Within those 120 seconds, though, anyone who has the invite can use it. If someone copies the invite and uses it before you do, the issuer gets their request instead of yours, and your own join is rejected because the invite was already used. The five words catch this. Each side computes them from the invite’s secret and both devices’ endpoint ids, so an attacker’s request produces different words from yours.

rex-iroh pair --accept skips the prompt and with it the word check: whoever uses the invite first is paired. Use it only when you’re sure nobody else can see the invite before you use it.

The protocol spells out how the words are computed and why they hold up.

The connection

rex-iroh connects devices with iroh, which encrypts each connection end to end with QUIC and authenticates both ends by their keys. Devices find each other through n0’s public relay servers and address lookup service. When they can’t reach each other directly, traffic passes through a relay. Relays carry the encrypted connection but can’t read it.

Revocation

When serve is running, peers revoke takes effect immediately: the device’s open connections close, and new ones are refused. Removing its line from the allowlist by hand does the same within about two seconds, the next time serve checks the file, but only if the rest of the file is valid. If any line is unreadable, serve keeps the previous allowlist, device included. Prefer peers revoke, and run peers list after editing the file by hand to confirm the device is gone.

Local files and sockets

rex-iroh creates its key, allowlist, control socket and the sockets connect opens so that only your user can use them. Someone who can already act as your user on a machine can use them too, but they could use your Rex server directly anyway.