The sync model
Synchronization is a live, pairwise exchange between two linked vault installations. Signaling helps the devices find each other. WebRTC data channels carry the data directly when possible; a TURN server can relay the same encrypted traffic when a direct route cannot be established.
- Find the peer
Signaling exchanges connection details; WebRTC opens a direct or relayed data channel.
- Establish an authenticated session
Keys exchanged during linking authenticate the peer and establish encryption for sync messages.
- Compare and transfer records
Both peers exchange record summaries and request the missing or newer records.
Session establishment
Linking stores the peer's signing and key-encapsulation public keys, a shared sync identifier, and connection-server configuration. Subsequent synchronization sessions use that saved relationship to locate and authenticate the peer.
Signaling carries WebRTC connection negotiation. STUN helps discover network addresses, and TURN provides a relay when a direct route is unavailable. A successful signaling connection does not guarantee that a WebRTC data channel can be established.
Over that channel, ML-KEM-768 establishes shared secret material and ML-DSA-65 authenticates the handshake using the saved peer keys. HKDF-SHA-256 derives a session key bound to the handshake transcript. AES-256-GCM protects subsequent messages with authenticated context and ordered sequence numbers. See the cryptographic protocol reference for the encryption details.
Record exchange
The initiating peer sends SyncHello with summaries of its credentials and directories. The other peer returns its summaries in SyncHelloEcho. Each side independently compares the remote summaries with its local records.
A SyncDataRequest identifies the records needed by item type and ID. The peer returns those records in SyncDataResponse, and the receiving client applies them to its local vault. Unchanged records do not need to be transferred in full.
Synchronization exchanges vault records over the encrypted session. Each installation keeps its own local encryption and unlock settings.
What completion means
Each device records completion after saving the records it requested, or after comparing summaries and finding nothing it needs to request. A failed local save does not advance that device's last-sync status.
Completion describes that device's comparison with one peer at that time. It is not an acknowledgement that the peer has saved changes sent in the other direction, or that every linked device has received them. Later edits require another exchange.
Changes, conflicts, and deletions
Each credential and directory carries an ID, version, modified timestamp, hash, and deletion flag. Peers first exchange these summaries. A device requests a full record when it is missing locally or when the remote record wins the comparison.
| Situation | Result implemented by the client |
|---|---|
| Different versions | The larger version wins. |
| Same version, different content | The later modified timestamp wins. |
| Same version and timestamp | The lexicographically smaller hash is the deterministic tie-breaker. |
| Credential deleted | A tombstone remains so the deletion can propagate to another device. |
| Directory deleted | Its record is tombstoned and contained credentials are scrubbed and tombstoned. |
A tombstone is a retained deletion record. It keeps the item's identity and version information so other devices can apply the deletion. For a deleted credential, its sensitive contents are removed.
Conflict resolution is record-wide. It does not merge the username from one edit with the notes from another. Device clocks participate when equal-version records differ, so badly skewed clocks can affect which concurrent edit wins.
Three or more devices
Sync is pairwise, not a broadcast transaction. If device A syncs with B while C is offline, C remains unchanged. Later, B can carry the winning records to C, or A can sync with C directly. A change has reached every device only after a chain of successful pairwise sessions covers them all.
When several devices edit the same record before meeting, each pair applies the same version, timestamp, and hash ordering. This gives them a deterministic result as those sessions complete.
Implementation references
These links point to the source revision used for this description, so the references remain stable as the code changes.
Message definitions: the encrypted envelope, record summaries, requests, and responses exchanged by peers.
Synchronization engine: session authentication, message ordering, record comparison, and completion handling.
Deletion and conflict rules: credential tombstones and the version, timestamp, and hash comparison used when accepting records.
Web vault persistence: applying received records and propagating save failures to the synchronization engine.