Per-device KeeShare sync — interop between KeePassDX and KeePassXC

[Lcstyle]

Hey everyone,

I implemented KeeShare support in KeePassDX with a per-device sync mode that eliminates file conflicts when syncing via Syncthing between multiple devices (phones, tablets, desktops).

The problem: classic KeeShare has all devices read/write the same container file. When two devices edit their databases and Syncthing syncs, you get conflicts.

The solution: each device writes its own container file ({DEVICE_ID}.kdbx) into a shared sync directory, and imports entries from all other devices' files. No two devices ever write the same file.

What the KeePassDX implementation includes

• Full KeeShare import/export with per-device container files
• Device identity system (configurable, falls back to Syncthing device ID or Android ID)
• Auto-upgrade of classic KeeShare references to per-device mode
• Directory watching + Syncthing REST API event polling for real-time sync
• Scoped group merge (entries import into the correct group, not root)
• Comprehensive docs and design plan

Fork branch: https://github.com/Lcstyle/KeePassDX/tree/feature/keeshare-support

Desktop interop

I also implemented the matching desktop side in KeePassXC so the two can interop seamlessly: https://github.com/Lcstyle/keepassxc/tree/feature/per-device-keeshare-sync

Discussion on the KeePassXC side: keepassxreboot/keepassxc#13080

This is still untested in real multi-device scenarios, but both builds work and unit tests pass. I'll be testing it with my own Syncthing setup soon.

Would love to hear thoughts on this approach. Happy to clean things up if there's interest in getting this upstream.

[J-Jamet]

As this was the first request of its kind, I wasn't sure what to make of this AI implementation. It has significant drawbacks, because even though it seems to work at first glance for your specific needs and has some interesting features, many aspects are unsatisfactory. So I conducted a general study of the solution and carried out an initial review.
I had already ruled out the KeeShare feature for the time being, as it requires numerous architectural prerequisites in addition to the various constraints of KeePassDX;

• KeePassDX should not manage any files or folders itself, only data streams provided by URI with an external file manager. This ensures that no traces of data from Keepass databases are retained.
• KeePassDX is not yet capable of managing/opening/editing multiple databases simultaneously. Currently, this feature is not implemented because it requires a structural change to be able to manage simultaneous service actions on multiple databases. It is necessary because it allows the application to manage data that could be shared and managed by multiple URIs for different database file streams.
• File synchronization tool APIs should not be directly integrated into KeePassDX. There is no reason to favor one tool, protocol, or cloud over another.

Here are my comments after reading the code you generated in your fork.

What's wrong :

• It's not easy to read; the readme talks about the limitations of the KeePassXC code in KeePassDX, even though the prerequisites are not the same. KeeShare is basically supposed to be the sharing of one database contained within another, but there is a lot of code and logic that is not related to this use case, so we naturally see that there are other basic features that are not present and that AI is trying to compensate for without considering the overall architecture.
• Al code is based on direct file reading with cache creation, this completely invalidates the basic purpose of KeePassDX.
• URL and network connections must be configured on an application that is normally purely local.
• The code is specifically geared towards Syncthing with polling on a REST API, which is the worst way to synchronize items and limits functionality to a single file synchronization protocol when it should not.
• The file synchronization logic is located in the global database actions service, with a lot of code that does not belong there.

What's right :

• The description of the model and data formatting of KeeShare for groups and entries can be reused in a more structured code (DeviceIdentity, KeeShareReference)
• The conflict management logic and sync direction can be reused in the dedicated file manager that will provide the data streams.
• The utility functions of the KeeShareContainer object are well designed.
• Unit tests related to utility classes
• AI has detected a small issue; a ticket needs to be created for this : DatabaseInputKDBX.kt` lines 543, 595

FileSync is currently being developed. It is designed to handle the conflicts you mentioned here, but in a generic way for all file types. KeeShare will then be developed based on this foundation.
The logic in your fork will be reused, but structured and architected correctly and cannot be integrated into KeePassDX in this way.
KeePassDX was originally created explicitly to avoid any strong dependence on a file protocol and to be completely local, and the code you provide breaks these first two principles from the very first lines of code.

[Lcstyle]

Thank you for taking the time to review the idea. Let me parse through your comments to try to understand the why behind the concerns.

[Lcstyle]

OK, take a look here: https://github.com/Lcstyle/KeePassDX/tree/feature/keeshare-saf-clean I cleaned everything up and you should find the docs a little bit easier. I also fixed the modification issue:

AI has detected a small issue; a ticket needs to be created for this : DatabaseInputKDBX.kt` lines 543, 595

228ef29

[Lcstyle]

Update: I've addressed your feedback @J-Jamet and have the sync working properly now. Still testing but so far it looks good.

What changed since the SAF-clean branch

Full diff of the new commits: Lcstyle/KeePassDX@v0.1.0-perdevice...v0.2.0-perdevice

Key fixes:

• Fixed sync storm — auto-triggered syncs (ContentObserver/polling) now only import, never export. Export only happens on user database save. This matches KeePassXC's ShareObserver pattern and prevents the feedback loop I was seeing with Syncthing.
• Fixed KeeShareReference bitmask parsing — KeePassXC uses ImportFrom=1, ExportTo=2 as bitmask flags, not enum ordinals.
• Added sync folder picker in Settings > KeeShare so users can configure the SAF folder before first sync.
• Added SAF folder provisioning prompt — on first manual sync, if groups have a classic KeeShare reference but no PerDeviceSync config, prompts user to pick the local sync folder.
• Improved import logging — tracks actual new entries merged vs container entry count.
• 16KB page alignment for Android 15+ native libs.

All file I/O goes through SAF — no direct filesystem access, no Syncthing API, no network connections.

Release

APK binary: https://github.com/Lcstyle/KeePassDX/releases/tag/v0.2.0-perdevice

Would you like me to open a pull request?

[J-Jamet]

16KB page alignment for Android 15+ native libs is already done in #2074 and is not related to the KeeShare issue.
KeePassDX 4.4.0 (view)
Can you open a pull request linked to the develop branch?

[Lcstyle]

#2438