Crate bitwarden_shared_unlock

Expand description

§Shared Unlock Protocol

Synchronizes vault lock state across multiple Bitwarden clients (web, browser extension, desktop) running in the same session. When a user unlocks their vault on one client, the unlock propagates to all connected clients.

§Leader-Follower Model

The protocol uses a leader-follower architecture where each client type has exactly one leader determined by the device hierarchy:

  Web Client  ──follows──▶  Browser Extension  ──follows──▶  Desktop App
  CLI Client  ──follows──▶  Desktop App

Leader: Holds authoritative lock state, broadcasts state changes to all followers.
Follower: Reports local state changes to its leader, applies authoritative updates from the leader.

A client can be both a leader (to clients below it) and a follower (to the client above it) simultaneously. For example, the browser extension leads web clients while following the desktop app.

§Message Types

All messages are serialized as CBOR and sent over the IPC transport.

Message	Direction	Purpose
`StartSession`	Follower → Leader	Announce presence with current lock state
`LockStateUpdate`	Bidirectional	Propagate lock/unlock events
`HeartBeat`	Bidirectional	Keep session alive, suppress vault timeout

§Session Lifecycle

§Follower Startup

  Follower                          Leader
    │                                 │
    │──StartSession(user, state)─────▶│  Follower announces itself
    │                                 │  Leader applies state if unlocked
    │◀─LockStateUpdate(user, state)───│  Leader responds with authoritative state
    │                                 │

On startup, the follower sends a StartSession for each logged-in user. If the follower is unlocked and the leader is locked, the leader unlocks using the provided user key. The leader always responds with a LockStateUpdate containing the authoritative state.

§Lock/Unlock Propagation

User unlocks on follower:

  Follower A                        Leader                         Follower B
    │                                 │                                │
    │──LockStateUpdate(Unlocked)─────▶│                                │
    │                                 │──unlocks locally──             │
    │                                 │──LockStateUpdate(Unlocked)────▶│
    │                                 │                                │──unlocks locally──

User locks on leader (via device event):

  Leader                          Follower A                     Follower B
    │                                 │                                │
    │──LockStateUpdate(Locked)───────▶│                                │
    │──LockStateUpdate(Locked)────────┼───────────────────────────────▶│
    │                                 │──locks locally──               │──locks locally──

§Heartbeat Keep-Alive

  Follower                          Leader
    │                                 │
    │──HeartBeat(user)───────────────▶│  Every N seconds
    │                                 │  Leader updates last-seen timestamp
    │◀─HeartBeat(user)────────────────│  Leader echoes back
    |◀─LockStateUpdate────────────────│  Leader always sends an authoritative state update to prevent desyncs
    │──suppresses vault timeout──     │
    │                                 │

The follower sends a HeartBeat for each logged-in user every HEARTBEAT_INTERVAL On receiving the echo, the follower suppresses its vault timeout timer, keeping the vault unlocked as long as the session is active. Stale sessions are pruned.

§Security Definitions

Attacker Model:
- Attacker gains user-space access to the device while the vault has been locked (steals the device)
Security Goal:
- Attacker cannot gain access to the vault key material

This security definition is aimed at stolen or seized devices. Forensics should not uncover (passively) recorded or otherwise left behind key material. The IPC encryption prevents such a compromise.

There is no further protection provided against active attackers running in userspace while the vault is unlocked on any of the clients on the device.

Attacker Model:
- Attacker controls a website that is not the web vault
Security Goal:
- Attacker cannot gain access to the vault key material

This is met by origin validation.

Modules§

drivers 🔒: Drivers that need to be implemented per platform for the shared unlock system.
follower 🔒
leader 🔒
message 🔒

Structs§

Follower: Tracks local state and follows authoritative lock updates from a leader.
FollowerStartError: Error type for failure to start the shared unlock follower.
Leader: Coordinates shared unlock state as the authoritative endpoint for followers.
LeaderStartError: Error type for failure to start the shared unlock leader.
UserKey: Wrapper type containing a serialized user key used for unlock propagation.

Enums§

DeviceEvent: The device (client) has several events that need to be reported to the shared unlock system. This enum represents the events that need to be reported.
FollowerMessage: The messages sent from followers to the leader
LeaderMessage: The messages sent from the leader to followers
LockState: Represents the lock state of a user.

Constants§

HEARTBEAT_INTERVAL: Interval used by followers to send heartbeat keep-alive messages to their leader.
VAULT_TIMEOUT_GRACE_PERIOD: Additional grace period added to the vault timeout when suppressing it on heartbeat

Traits§

SharedUnlockDriver: Trait that implmeents the device’s shared unlock driver. These functions need to be implemented in order to allow the shared unlock system to function.