Skip to content

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 separate machine role.

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 protection attribute (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.