0008: Members are sets of device keys; Signal-style device linking
- Status: accepted
- Date: 2026-09-22
Context
A human uses several devices: a laptop, a phone that approves unlock requests, a hardware token. Copying one private key between devices is fragile and encourages bad habits, and it makes losing one device equivalent to losing them all. Approval from a phone (ADR 0011) requires the phone to hold a key that can unwrap the member's KEKs.
Decision
- A member is a policy-level identity (display name, contact) with a set of device keys. Roles attach to the member; KEK wraps attach to device keys.
- Each device generates its own keypair locally, in hardware where available (ADR 0009). Private keys never leave the device.
- Linking follows the Signal model. The new device displays a QR code containing its public key and a one-time relay session id. An existing device scans it; the physical scan is the out-of-band verification. The existing device then, over the relay end-to-end to the new key, writes one wrap file per epoch it holds for the new key and signs a policy event "device D2 belongs to member M, authorised by D1". Nobody else in the vault needs to act.
- Device revocation has two grades, chosen by the human, defaulting to
the paranoid one:
- Lost, believed locked (hardware-protected key behind biometrics or full-disk encryption): policy event revokes the device key, no new epoch.
- Compromised: revoke the key and mint a new epoch (ADR 0007), since the device held the KEKs.
- Member revocation is "revoke every device of M plus new epoch" and shares the code path.
- Machine identities (CI, servers, daemons) are ordinary members carrying a
machine flag, with a single device key, scoped to specific collections.
They hold one of the four roles, normally
reader; there is no separatemachinerole.
Consequences
- One additional wrap file per epoch per device; still additive.
- Policy and audit can name the device, not just the member.
- Linking requires either the relay or a local channel; a QR-only local flow works without any network when both devices are physically present.
- Admins can require hardware-protected device keys for sensitive
collections via the
protectionattribute (ADR 0009).
Alternatives considered
- One key per member, exported to each device. Rejected for the reasons in the context.
- Device keys derived from a member master key. Rejected: any one device could derive the others, defeating per-device revocation.