Trusted-device unlock

A trusted mobile device can unlock your vault in the browser without typing the Access Key: the browser asks, the phone approves with a biometric, and the master key travels through an ephemeral end-to-end encrypted channel the server cannot open. This page describes the protocol for security reviewers.

How a phone becomes trusted#

There are two paths, both ending in the same state — a device wrap of the User Master Key:

1. Mobile signup — an account created on the phone completes the key ceremony, then registers a device wrap: the UMK encrypted with RSA-OAEP-2048 to a hardware-backed key generated in the Secure Enclave (iOS) or Android Keystore. Registering the wrap establishes trust automatically.
2. QR pairing — from an unlocked browser session, the user generates a short-lived setup token rendered as a QR code. The phone scans it, registers itself with its device public key, and the browser wraps the UMK to that key and uploads the device wrap.

The device private key is biometric-protected hardware material — it never leaves the enclave, and using it requires a successful Face ID / fingerprint event. Trust runs on a sliding window — 30 days by default, pushed forward on each authenticated use, so only a dormant device expires — and only one trusted mobile is honored at a time; a device counts as trusted only while it holds an active device wrap.

The unlock protocol (browser → phone)#

1. The browser generates an ephemeral X25519 keypair and initiates an unlock request with the ephemeral public key. The request expires 120 seconds after it is created.
2. The server pushes the request to the trusted phone over a live push channel; if the app was closed, it fetches its pending requests on open/resume. The browser shows a number-match code and polls for the result.
3. On the phone, the user types the number the browser shows — the phone is never sent it — then passes the biometric gate. The enclave key decrypts the device wrap, recovering the UMK.
4. The phone seals the UMK to the browser's ephemeral public key using a libsodium sealed box (crypto_box_seal) and sends the ciphertext with the number the user typed. The user can instead deny, which resolves the browser immediately.
5. The browser opens the sealed box with its ephemeral private key, recovers the UMK, and receives its vault session — gate 2 is satisfied.

Why each piece is there#

Defense	Threat addressed
Number match (user-verified)	Approving an attacker's unlock request (MITM/phishing of the approval)
Ephemeral per-request X25519 keys	Replay of an old handoff; forward secrecy of the channel
Sealed box encryption	The server relaying the message can never read the UMK
Biometric-gated enclave key	Remote-only phone compromise cannot use the device wrap
120-second request TTL	Stale or forgotten requests cannot be approved later
Session binding + rate limiting + replay protection	Abuse of the unlock endpoints
Sliding trust window (30 days of disuse by default), one-trusted-mobile limit	Bounding long-lived trust without expiring a device in daily use

Pending-request listing, approval and denial require the phone's own signed-in session: a mobile session that the server linked to the trusted device when the phone signed in, paired or uploaded its device wrap. A device identifier sent in a request header is never enough, so a stolen login token used from another device gets an empty list or a refusal.

The vault session the browser receives is bound to the browser's own login session. It stops working when that login session ends — sign-out, "sign out other sessions", or a revoked session — and it cannot be used from another login session of the same account. Its length is always one of the durations the unlock screen offers, whichever way the vault was unlocked.

Related#

• Device trust — the concept for users
• Devices — managing devices in the console
• Encryption architecture — where the device wrap fits