Stolen-device rescue and the trusted circle
A stolen phone or laptop that's still unlocked is the most likely way a Pigeon account gets attacked. The design aims to make taking it back fast, and to make sure a thief can't lock you out.
What a thief can and can't do
With an unlocked device, before you act, a thief can read new messages, send as you, and link or remove devices. Each of those is visible on your other devices. What they can't do is rotate your account's root key, as long as your seed phrase is kept apart from the device.
Taking it back Built
- Revoke: any of your other devices can remove the stolen one at once.
- Rotate: entering your seed phrase rotates the root key and cuts out the thief.
Quarantine Planned: entering the seed phrase on a new device would remove the stolen device from every group within about one key-log epoch (around 15 minutes) instead of waiting out a time-lock. Its key events are in the core, but they only take effect in an account with time-locked rescue, below, which no account has yet.
Time-locked rescue Planned
The full rescue design adds a time-lock to account changes, with factors you enrol: each device, the seed phrase, and optionally a hardware security key (FIDO2 or passkey), up to 16 devices and 4 keys.
- A change proposed by a device waits for the time-lock (24 hours, 72 hours, 7 days or 30 days; 72 hours by default). Any one factor can cancel it.
- A change proposed with the seed phrase alone also waits, and cancelling it takes two different non-seed factors. The seed phrase can't cancel its own kind of proposal.
- The seed phrase plus one other factor applies at once, but only to remove devices or rescue the account.
The client-side check of these rules is built in the core; the public log that enforces them is not deployed, and this layer isn't in the desktop alpha.
The trusted circle Built
More on the circle and on group alerts: the trusted circle and group transparency.
The trusted circle is a short list of people who are told if your account is recovered or taken over, so someone notices if it wasn't you. Its members don't approve or vote on anything; they are only told.
- It's empty by default.
- It's stored in your own key log as keyed tags, padded to buckets of eight, so the log doesn't reveal who is in it.
- People are told when they're added or removed, and can leave.
- Everyone else who shares a conversation with you sees at most “Security keys changed on <date>”.
Trusted contacts as rescue factors, and inheritance, are a later phase Planned.
Sources: ADR-0005 (identity, revoke and rotate), ADR-0010 (time-locked rescue and the trusted circle), ADR-0014 (what's in the desktop alpha), crates/pigeon-core/src/identity/circle.rs, crates/pigeon-core/src/identity/rescue.rs.
Related: identity and seed phrases.