- Go 99%
- Shell <1%
rerouted #
rerouted is the reference homeserver for Tieroute, a federated, end-to-end encrypted (E2EE) chat protocol. This page says what rerouted implements, and where to start, whether you want to run it or work on it.
A homeserver holds its users' identities, and stores their messages until their devices fetch them. rerouted never needs to read a message: clients encrypt everything with Messaging Layer Security (MLS), and rerouted routes by the delivery envelope alone. It's written in Go, without cgo, and keeps its data in one SQLite database and a directory of files.
rerouted is alpha software, maintained by Reroute Holdings LLC, and it runs the public alpha homeservers. It speaks Tieroute wire versions 1 and 2 side by side, each under its own API base. Wire version 2 comes from the current spec, version 2.0, which adds post-quantum signatures, a migration from wire version 1, and community servers. rerouted implements every wire version 2 endpoint in the spec's Appendix A, including the migration and community servers.
Install #
rerouted is packaged for Debian, Ubuntu, Fedora, and Arch Linux, on amd64 and arm64, in the same signed repository as the Reroute app. On Debian or Ubuntu:
sudo curl -fsSLo /usr/share/keyrings/reroute-archive-keyring.gpg https://rerouteholdings.llc/reroute/linux/reroute-archive-keyring.gpg
echo 'deb [signed-by=/usr/share/keyrings/reroute-archive-keyring.gpg] https://rerouteholdings.llc/reroute/linux/apt stable main' | sudo tee /etc/apt/sources.list.d/reroute.list
sudo apt update && sudo apt install rerouted
sudo rerouted init
On Fedora, add the repository with sudo rpm --import https://rerouteholdings.llc/reroute/linux/reroute-archive-keyring.asc and sudo curl -fsSLo /etc/yum.repos.d/reroute.repo https://rerouteholdings.llc/reroute/linux/rpm/reroute.repo, then run sudo dnf install rerouted. For Arch Linux, and the key's fingerprint, see Install Reroute on Linux, and install rerouted. Signed release tarballs are in https://rerouteholdings.llc/reroute/linux/rerouted/. Run a homeserver has the whole setup.
Documentation #
- Run a homeserver: from a fresh Linux server to people signing up.
- Run a call relay: relay your users' calls, so they don't show each other their IP addresses.
- Administer a homeserver: back up, control registration, and handle reports.
- Settings: every setting, its default, and what it does.
- Send push notifications to the Reroute iPhone app: an optional feature outside the Tieroute spec, with content-free notifications.
- Public firehose: an optional public feed of delivery metadata, for development servers.
- How rerouted stores moves and recovery wraps: how the multi-record changes stay consistent.
The protocol itself is documented in the Tieroute specification, the client API reference, and the server-to-server API reference.
What it implements #
rerouted implements every wire version 1 and version 2 endpoint in the spec's Appendix A, for clients and for other servers. Comments in the code cite the spec section each rule comes from, such as SPEC §11.6. Section numbers are those of the current spec.
| Area | Spec | What rerouted does |
|---|---|---|
| Encoding | §4 | I-JSON (the Internet JSON profile) with duplicate-name, UTF-8, and integer checks; strict base64url; and the JSON Canonicalization Scheme (JCS) for everything signed or hashed |
| Discovery | §5, §8.1 | The server document and handle documents. Reserved handles can't be registered. Handle changes: a new name under the handle domain has to be free, and a name an identity stops using, by a rename or a move away, is held for it for 30 days, then freed unless the operator keeps it (keep-handle). Server keys rotate on their own: a successor is published when a key is 300 days old, and signs a week later (rerouted keys). |
| Identities | §6 | Identity chains and the fork rule, vouching, tombstones, recovery with the recovery key, alerts on device changes, and moves between homeservers |
| Devices | §7 | Two-way device approval with link proofs, including approval codes a new device scans (listed with GET link/proofs), wrapped account keys, versioned account data, and backups |
| Contacts | §9 | Registration and contact requests by invite code; accept, decline, cancel, remove, block, and unblock; and the rate limits |
| Delivery | §10 | Send, inbox, acknowledge, and a WebSocket stream. Deliveries to other servers wait in a durable outbox, and are retried with backoff for up to 72 hours. |
| Groups | §11 | The hub, which orders a group's changes, with epoch keys and signed receipts; commits through a remote hub; missed commits; and hub handoff |
| Presence and profiles | §13 | Presence for mutual contacts only, and signed profiles with checked profile pictures |
| Files | §14 | Uploads up to 64 MiB under a quota for each identity, fetched through the recipient's own homeserver and deleted after 30 days |
| Calls | §15.1 | Time-limited credentials for a TURN (Traversal Using Relays around NAT) relay |
| Reports | §17 | Reports kept for the operator, and optionally forwarded to the reported identity's homeserver |
| Community servers | §16 | Every endpoint in the community server API, for any number of server names with one community each: the community chain, the hub for the community's groups, channel sequence numbers, history segments, read positions, files, reports, and voice channels through an SFU (selective forwarding unit) on Pion WebRTC. Settings explains how to turn them on. |
What isn't built yet:
- Migrating to a version 2 identity on another server. It starts on the version 1 identity's homeserver, and moves afterwards.
- The public firehose shows wire version 1's deliveries only.
- Batching several deliveries into one server-to-server
delivercall. Each call carries one, which the spec allows. - Registration codes with use counts or expiry dates. There's one code,
REROUTED_REGISTRATION_CODE. - Combining presence updates for each destination server. A small server may send each one right away (SPEC §13.2).
- A rate limit on
recoverfor each identity and address. - Undoing a community commit that a rerouted before 0.2.0-rc.3 sequenced. It didn't keep the epoch's state that undoing needs, so
POST groups/undoanswers404 not-foundfor it, and the community's groups are re-created instead (SPEC §16.5).
Try it locally #
You need Go, at the version in go.mod.
-
Build rerouted:
go build -o rerouted ./cmd/rerouted -
Start it with a throwaway database:
REROUTED_NAME=chat.example REROUTED_STORE=temp ./rerouted -env /dev/null -
In another terminal, fetch its server document:
curl -s http://127.0.0.1:8080/.well-known/tieroute/serverIt prints a JSON object that starts with
{"apis":.
To run it for real, follow Run a homeserver.
Develop #
Check and test your changes:
gofmt -l .
go vet ./...
go test -race ./...
Tests run against real SQLite databases in temporary directories, and the federation tests start two homeservers in one process. The files in testdata/vectors/ are copies of the spec's test vectors for wire version 1, and those in testdata/vectors/v2/ are for wire version 2.
| Path | What's there |
|---|---|
cmd/rerouted/ |
The server and its admin commands |
cmd/linetest/ |
A scripted client that drives two homeservers over HTTP, for end-to-end tests |
internal/api/ |
HTTP routes and handlers, one file for each area of the API |
internal/chain/ |
Identity chains: validation, the fork rule, alerts, and clock checks |
internal/fed/ |
Federation: server documents, signed server-to-server calls, and handle resolution |
internal/store/ |
The storage interface, and its SQLite implementation in sqlite/ |
internal/wire/ |
JSON encoding, signed envelopes, identifiers, chain entries, and error codes |
internal/ws/ |
The server side of the WebSocket protocol (RFC 6455), on the standard library |
internal/config/, internal/serverkey/ |
Settings, and the server's signing key |
packaging/ |
The systemd units, and the configuration and scripts for the packages |
scripts/release.sh |
Builds a release: tarballs and packages for Linux |
deploy/ |
Example Caddy and coturn configurations |
docs/ |
Guides and reference for operators |
Before you send a change, read CONTRIBUTING.md. To report a vulnerability, follow SECURITY.md, and don't open a public issue.
License #
You can use rerouted under the MIT license. See LICENSE. Reroute Holdings LLC also pledges never to assert its patents against Tieroute implementations: see PATENTS.md.