Pairing devices

Pairing adds a device to the set of machines that share your Manuscripts, Codexes, and Tome. Pairing happens through Guild, the paid encrypted relay.

The handshake produces an MLS group (RFC 9420) that holds the keys for that device set. Trove never holds an unencrypted copy of your work — the relay routes opaque ciphertext only.

Guild pairing

Pairing requires an active Guild subscription on the account. Both devices open Settings → Devices & Sync; the flow is a two-way code exchange:

1. On the existing device, choose Pair another device.
2. The new device shows a code — paste it on the existing device; the existing device answers with its own code, which you paste back on the new device.
3. The new device joins the device group; the two exchange MLS key material via the relay. The relay sees envelope metadata it needs to route. It does not see the keys themselves.

After the handshake, both devices appear in the device list in Settings → Devices & Sync.

What gets shared at pairing time

A successful pair grants the new device read/write access to:

• Every Manuscript currently in your Trove root.
• Every Codex linked from those Manuscripts.
• The user-wide Tome.

The new device pulls a full snapshot on first sync via the relay, then receives incremental MLS commits as you edit.

Unpairing a device

From Settings → Devices & Sync you can remove a device from the group (or unpair all devices to reset the set). Removal triggers an MLS commit that drops the device’s key package. The next time a peer applies that commit, the removed device can no longer decrypt new envelopes. Local files on the removed device are not touched; they just stop receiving updates.

The full protocol is documented in the repo at docs/FEDERATION.md and docs/CRYPTO_SPEC.md.