Reference server for Tieroute protocol.
README.md

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 #

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 deliver call. 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 recover for 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/undo answers 404 not-found for 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.

  1. Build rerouted:

    go build -o rerouted ./cmd/rerouted
    
  2. Start it with a throwaway database:

    REROUTED_NAME=chat.example REROUTED_STORE=temp ./rerouted -env /dev/null
    
  3. In another terminal, fetch its server document:

    curl -s http://127.0.0.1:8080/.well-known/tieroute/server
    

    It 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.