Architecture decisions
Architecture decision records (ADRs) live in docs/adr in the repository. If a change conflicts with one, say so in your pull request rather than quietly working around it.
ADR 0001: The History key is random and separate from the Recovery key
Status: accepted
Group Epoch keys and Personal data are encrypted to a random, versioned History key. The Recovery phrase only derives a Recovery key, which only protects one Recovery escrow per History key version.
Why:
- A History key can be replaced without the user writing down a new phrase.
- A Phrase change re-seals the escrows without touching any History wrap or Personal data.
- A Restore downloads and opens the escrows; nothing is re-encrypted.
- The Recovery private key only exists in memory during setup, Restore, Phrase change and Recovery reset.
- The phrase isn't tied to a server, so a self-hoster who moves their database keeps the same phrases, as long as user IDs are kept.
Options rejected: deriving the History key from the phrase, because replacing the key would force a new phrase; and handing the History key from one device to another without a phrase, because until devices can be verified the server would decide which device receives it.
Consequences: the server stores one escrow per History key version. Anyone with both the phrase and the escrows can read the account's history, so escrows are only served to the signed-in account. Until device keys and History public keys are signed, the server is trusted to publish the right public keys.
ADR 0002: Every account has a History key
Status: accepted
Every account gets History key v1 when its first device registers, with no Recovery escrow. Setting up a Recovery phrase seals an escrow for every existing version instead of creating v1.
Why: without it, an account with no phrase has nothing a new device could be given, so a Device link would only work for accounts with a phrase. It also moves Personal data off a single phone's Device key.
Device links: a new device gets every History key version from an Active device of the same account by showing a QR code with its Device public key and a 32-byte secret that never reaches the server. The Active device checks the server's record of the new device's key against the code and seals the keys with HPKE AuthPSK. This answers ADR 0001's objection to device-to-device handover: the server no longer chooses the receiving device.
Consequences:
- Accounts without a phrase hold History key versions with no Recovery escrow, and Restore never offers them.
- Setting up a phrase needs a device that holds every History key version.
- Once every device has been removed, the next one is Pending and can only be set up by Restore or a Recovery reset.
- The new device trusts the server for the approving device's public key until devices can be verified.