Glossary
Use these terms in issues, code, tests and docs. Each entry lists words to avoid, so everyone means the same thing.
Encryption
| Term | Meaning | Avoid |
|---|---|---|
| Epoch | One generation of a group's encryption key. A new one starts when a group is created, someone joins or leaves, or a rotation is due. | Key version, generation, session |
| Epoch key | The symmetric key of one Epoch. It encrypts the group's tracking data for that Epoch. | Group key, shared key |
| Device key | A key pair created on one device for one account. Its private half never leaves that device. | Account key, user key, identity key |
| Device wrap | An Epoch key encrypted to one Device key. | Wrapped key, recipient key |
| History wrap | An Epoch key encrypted to one account's History key, for one History key version. | Account wrap, backup wrap |
| Recovery phrase | The 12 words a user writes down to get their History key onto a new device when they have no other device to link from. Never stored or sent. | Seed phrase, mnemonic, recovery code |
| Recovery key | The key pair derived from the Recovery phrase. It only protects Recovery escrows. | Master key, seed key |
| History key | A random, versioned key pair per account that protects History wraps and Personal data. Every account gets one when it's created, with or without a Recovery phrase. | Account key, archive key |
| Recovery escrow | One History key version's private key, encrypted to the Recovery key and stored on the server. Only accounts with a Recovery phrase have them. | Backup, key backup |
| Active device | A device that has been set up, so it's in its account's Epochs and can send and see locations. Only an account's first device ever is active as soon as it registers. | Approved device, trusted device |
| Pending device | A device signed in to an account that has had an Active device before, and not yet set up. It can only be set up or removed. The server deletes it if it isn't set up within 7 days. | Unapproved device, new device |
| Activation | A Pending device becoming Active: through a Device link, a Restore or a Recovery reset on that device. The account's groups then start a new Epoch. | Approval, enrolment |
| Device link | A Pending device getting every History key version from an Active device of the same account, which scans a QR code the new device shows. Codes expire after 10 minutes. | Pairing, sync, transfer |
| Enrolled device | A device that holds the account's current History key, because it created it, Restored it or got it through a Device link. | Trusted device, primary device |
| Backfill | An Enrolled device adding History wraps for Epochs it can already read. | Sync, re-wrap |
| Restore | Getting every History key version that has a Recovery escrow onto a device by entering the Recovery phrase. | Recover, import |
| Phrase change | Replacing the Recovery phrase from an Enrolled device. History key versions stay the same. | Rotation, reset |
| Recovery reset | Replacing a lost Recovery phrase when no Enrolled device is left, or making one when the account never had one. Deletes every History key version and starts a new one. On a Pending device it's "Start fresh". | Start over, wipe |
| Personal data | A user's nicknames for other members and their own group colours. Only that user can read it. | Profile data, settings |
In text users see, say "phone" for a device and "the group's encryption key" for an Epoch key.
Accounts
| Term | Meaning | Avoid |
|---|---|---|
| Email code | A 6-digit code emailed to prove the owner can read that inbox. Each has one purpose: sign-up, email verification, password reset or Recovery reset. | OTP, magic link, PIN |
| Session | One sign-in to an account. It's linked to a device when it registers that device, or proves it holds the device's Device key. Signing a session out doesn't remove the device. | Login, device |
| Device name | The name the owner gives a device, such as "Car tablet". A new device is named after its model. Stored in plain text and visible to group members. | Device label, nickname |
| Device icon | One of a fixed set of pictures for a device: phone, tablet, watch, car, laptop, bag, tag or home. | Device type, avatar |
| Removing a device | Taking a lost or stolen device off the account in Account › Devices. The server signs it out, refuses its requests and leaves it out of new Epochs; the phone wipes its keys next time it connects. Different from signing out. | Revoking, unlinking |
| Security alert | An email telling the owner something important happened to their account. | Notification, Place Alert |
| Always-on alert | A Security alert the owner can't turn off: password or Recovery phrase changed or reset, other sessions signed out, device removed, Security alerts turned off, and account deleted. | Mandatory alert |
| Optional alert | A Security alert the owner can turn off: new sign-in, and account deletion scheduled. | Preference |
Places
Places aren't built yet, but these terms are agreed.
| Term | Meaning | Avoid |
|---|---|---|
| Place | A named circular area shared by a group: centre, radius, name and emoji. | Geofence, zone, pin |
| Place Transition | A record that a member arrived at or left a Place. | Geofence event, check-in |
| Arrive / Leave | The two kinds of Place Transition. | Enter/exit, check-in/check-out |
| Place Alert | A notification to a member about another member's Place Transition. | Push, geofence notification |
| Place Alert Mute | A choice not to be notified about one member at one Place. | Silence, block |
| Dwell | How long a member must stay inside or outside a Place before a Transition is recorded. | Debounce, delay |