A user reported that they couldn’t delete a group from the Recycle Bin. Not on the desktop, not on the iPhone, not on the web. They deleted it, it disappeared, and a few seconds later it was back.
It turned out every client had the same bug, for the same reason, and fixing it meant rethinking how OpenVireo decides what a deletion means. This post is about that: why “sync the deletes too” is harder than it sounds, why the obvious timestamp-based answer is wrong, and the rule I ended up with.
The setup
Every OpenVireo vault is a KeePass (.kdbx) file. Each device keeps a full copy. The sync server only stores the encrypted file and can’t read it, so all merging happens on the devices. A sync is:
- Download the server’s copy.
- Merge it with the local copy.
- Upload the result. If someone uploaded first, the server refuses and you start again.
The merge is three-way. Each device also keeps a base copy: the version it last synced. With the base, you can tell “I changed this field” from “they changed this field”, which a two-way merge can’t.
Why deletes come back
Additions are easy to merge. If an entry exists on one side and not the other, and it isn’t in the base, it’s new: copy it over.
Deletions look exactly the same from the outside. An entry that exists on one side and not the other could be:
- new on the side that has it, or
- deleted on the side that doesn’t.
Without more information, a merge can’t tell those apart, and the safe default is to keep it. Losing a password is much worse than having one come back. So the KeePass format records deletions explicitly: a DeletedObjects list of UUIDs with the time each one was deleted.
OpenVireo inherited its merge from KeePassXC. KeePassXC’s Merger has a few modes, and the one all three clients used for sync, KeepNewer, never applies deletion records. It’s a reasonable mode for importing one file into another, where you don’t want the import to delete anything. For sync, it means every permanent delete gets undone by the next merge with a device that still has the item.
Two more problems were hiding behind that one:
- The upstream merge never merged the Recycle Bin’s identity. A bin created on one device arrived on another as an ordinary group. Deleting something from it there created a second Recycle Bin.
- The web SDK’s “delete from the bin” didn’t write a
DeletedObjectsrecord at all, so there was nothing for the other devices to see.
The obvious fix, and why it’s wrong
The obvious fix is the one KeePassXC’s Synchronize mode uses: compare times. If an entry was modified after its deletion time, keep it. Otherwise delete it.
That works when every device has a correct clock. They don’t. A phone that was off for a while, a laptop with a dead CMOS battery, a VM restored from a snapshot, someone who set the date forward to cheat in a game. With timestamp rules, a device whose clock is a week fast makes every one of its edits beat every deletion, and a device whose clock is a week slow can delete entries that someone edited yesterday. Either way the bug is invisible: no error, just the wrong data.
I wanted a rule where a wrong clock can’t decide anything.
The rule: decide against the base
The base copy already says what everyone agreed on at the last sync. That turns out to be enough:
Delete an item only if every copy still matches the base. If anyone changed it since, keep it.
In detail, the sync merge does this:
- Before the structure merge, find each side’s pending deletions: a deletion record on one side for an entry or group that’s gone on that side but still on the other.
- Run the structure merge. It brings those items back, as it always did.
- After the merge, decide each pending deletion against the base:
- Entries: delete from both copies if the entry is in the base, and every copy has the same fields and is in the same group as in the base. Both copies then carry the deletion record. Otherwise keep the entry and drop every deletion record for it on both sides.
- Groups, deepest first: the same, where a group matches the base when its name, notes, icon and parent are unchanged, and it’s only deleted when every copy is empty.
No timestamp appears anywhere in that rule. A device can be a year off and the outcome is the same.
The cases come out the way you’d expect:
| Device A | Device B | Result |
|---|---|---|
| deletes entry | doesn’t touch it | deleted everywhere |
| deletes entry | edits it | kept, with B’s edit |
| deletes entry | moves it to another group | kept, in the new group |
| deletes group | adds an entry to it | group kept, with the new entry |
| deletes entry | deletes it too | deleted, one record |
The “edit wins over delete” choice is deliberate. If two people disagree about an entry, keeping it costs a second delete. Deleting it costs a password.
Why the group rule says “empty”
Groups were the trickiest part. Suppose A deletes a group and its entries, while B adds a new entry to that group. If the group were deleted because its own properties match the base, B’s new entry would have nowhere to go. Deciding groups deepest first, and only deleting empty ones, means B’s entry survives, and so does every group above it.
Merging the Recycle Bin
The Recycle Bin is an ordinary KeePass group, except the database metadata names its UUID. Two devices that each enabled the bin while offline each have one. After a merge, both groups exist, and only one is “the” bin.
The rule:
- A side without a bin adopts the other side’s.
- With two bins, the one whose
RecycleBinChangedtime is later wins, compared in whole seconds (KDBX stores seconds, so a copy that’s been saved and reopened has lost its milliseconds). A tie goes to the lower UUID bytes, so every device picks the same winner without talking to each other. - The losing bin is emptied into the winner and deleted.
Yes, that one uses a timestamp. The difference is that it only chooses which of two equivalent groups to keep; nothing is lost either way, because the loser’s contents move into the winner.
Keeping three implementations in step
At the time, the merge existed three times: C++ in the desktop app, TypeScript in the web SDK, Swift on iOS. The fix had to land in all three and produce the same result. The approach:
- Recorded fixtures. The desktop’s merge results for each scenario are saved as files (base, local, remote, expected result), and copies of the same fixtures run in the SDK and iOS test suites.
- A written spec. The SDK has a merge behaviour document that describes outcomes, not code, so an implementation in any language can be checked against it.
Since then, the merge has moved into a shared Rust core, and the fixtures came along as its test cases. The rule only has to be right once now.
The clocks still matter to users
Even though the merge ignores clocks, other things don’t: TOTP codes, certificate checks, token expiry. While working on this, I added a small warning to every client. The sync server’s responses carry an HTTP Date header; the client compares it with its own clock and warns when they’re more than five minutes apart.
Two small things came up there:
- On the desktop, Qt’s RFC 2822 date parser rejects the
GMTthat every HTTP server sends, so it needed its own parser. - In the browser, JavaScript can’t read the
Dateheader on a cross-origin response unless the server lists it inAccess-Control-Expose-Headers. Without that one header, the web app never warns.
What I’d tell someone building sync
- Additions are easy. Deletions need a record, and the record needs a rule for when it applies.
- Don’t let clocks decide outcomes. If you have a common base, compare against it. If you don’t, consider whether you can keep one.
- When unsure, keep the data. A resurrected entry is an annoyance; a lost one is a support ticket you can’t resolve.
- Test with fixtures, not just unit tests. “Device A did this, device B did that, here’s the expected file” catches more than any test of a single function.