OpenVireo is a password manager with four clients: a web app, an iPhone app, a Qt desktop app forked from KeePassXC, and a command-line tool. Until recently, each one had its own copy of the protocol: account key derivation, OPAQUE sign-in, vault keys and sharing, share links, sync, and the three-way merge of KeePass files.
| Client | Language | Protocol code | OPAQUE library |
|---|---|---|---|
| Web, CLI, GitHub Action | TypeScript | ~7.9k lines | opaque-ke, compiled to WASM |
| iPhone app and AutoFill | Swift | ~10.1k lines (incl. 2.3k of KDBX) | a forked copy of the same Rust crate |
| Desktop | C++/Qt | ~7.8k lines | libopaque + liboprf + libsodium |
Now all four call one Rust workspace, openvireo-core. This post covers why I did it, where I drew the line between the core and each platform, how the bindings work, and how I made sure the new code behaves exactly like the old code before switching anything over.
Three copies drift
The cost of three implementations isn’t the typing. It’s that they slowly stop agreeing with each other.
A typical example: an entry moved to another group on one device, and edited on a second device before the move synced. The merge saw that the edited copy was newer and kept it whole, including its old group, so the move silently disappeared. The fix was a rule: note where each entry was moved last before merging, then put it back there afterwards. The rule itself is short. Shipping it took four commits in four repositories (desktop, TypeScript SDK, iOS, and a test fixture), each reviewed separately, each with its own chance of getting an edge case slightly differently.
That happened again and again: sync deletions, share links, account deletion, key rotation. Each feature was built three times. Worse, two different OPAQUE implementations were in production. Both implement RFC 9807, but “both follow the RFC” is a claim, and for the code that decides whether you can log in, I wanted bytes, not claims.
Why Rust
The web already ran Rust: OPAQUE came from opaque-ke compiled to WASM. Rust is also the one language that reaches every target I needed without a runtime:
- Web:
wasm-bindgen→ an npm package. - iOS: UniFFI → a Swift package and an xcframework.
- Desktop: cxx → a static library and a C++ header, built from source inside CMake with Corrosion.
- CLI: a plain native binary.
The licence matters too. The core is MIT OR Apache-2.0, so the GPL desktop app can link it, and so can anyone else.
The core does no I/O
The most important decision was what the core doesn’t do. It never opens a socket or a file, never reads the clock, never touches the Keychain. Each platform implements a small Host interface and passes it in:
Host http send(request) -> response URLSession · QNetworkAccessManager · fetch store get / put / delete secrets Keychain · DPAPI / libsecret · IndexedDB cache load / save vault blobs the offline copy clock now() log tracing sinkI could have put reqwest in the core and been done with HTTP in one place. I didn’t, because every platform already has opinions that users rely on:
- The desktop app has proxy settings, and people behind corporate proxies need them to keep working.
- iOS has App Transport Security, background sessions and the system trust store.
- The browser has
fetchand CORS, and nothing else. - TLS stays the platform’s job, patched by the platform’s updates.
It also keeps the dependency tree small, which matters twice: for the WASM bundle size, and for the iOS AutoFill extension, which runs under a tight memory limit.
The rule extends to the merge crate: it draws no randomness and reads no time. now comes in as an argument, and new UUIDs come from a function the caller passes in. That makes every merge reproducible in a test.
The only exception is the native CLI. It has no platform app around it, so it ships a reqwest host of its own.
Layout
crates/ ov-crypto Argon2id, HKDF, XChaCha20-Poly1305, X25519, Ed25519, zeroize ov-opaque opaque-ke wrapper ov-protocol wire types, error codes ov-vault account unlock key, keyset, keyring, vault keys, sharing, rotation ov-share share links ov-kdbx KDBX 3.1/4.x read and write ov-merge three-way merge on the KDBX model ov-sync sync state machine, deletions, clock-skew check ov-core the facade: Account, Vault, Sessionbindings/ ov-wasm, ov-wasm-lite, ov-ffi-swift, ov-ffi-cppbins/ ovCrates only depend downward: ov-core → domain crates → ov-crypto. Only bindings/* and bins/* know a platform exists.
A few rules apply at every FFI boundary:
- One error type (
OvError) with stable string codes, mapped to each platform’s existing error type, so client code didn’t have to change how it handles failures. - Secrets cross as byte buffers that the core zeroizes. Passwords aren’t kept as long-lived Rust
Strings. - No panics cross FFI. The binding layer catches them and turns them into
OvError::Internal. A panic unwinding into Swift or C++ is undefined behaviour, and a password manager is a bad place for that. - The facade is async. UniFFI and wasm-bindgen both support async exports and async foreign traits, so the platform’s HTTP stays non-blocking end to end.
Bindings have to expose the domain, not just the facade
My first version of the bindings exposed only the facade: Account, Session, a Vault handle you could sync. It looked clean, and it was wrong.
When I started moving the web SDK onto it, only the bottom layer could move: primitives, OPAQUE, TOTP, share links. Everything that worked with entries, groups and fields still needed the old TypeScript code, because the binding didn’t expose them. The bundle got 1.09 MB (gzipped) bigger and the old code stayed. iOS and desktop hit the same wall.
So I went back and widened every binding to expose the domain layer: entries, groups, fields, attachments, history, the Recycle Bin. Then each client became a thin wrapper over it. The lesson I’d pass on: if a binding forces the client to keep its own model alongside yours, you’ve built a second implementation, not a shared one.
WASM size
The full web binding is 864 KB gzipped. That’s a lot for a web page, so the web app lazy-loads it after first paint: you see the sign-in screen while it downloads.
The page that opens share links is different. It’s opened by people who don’t have an account and who just want one password. It gets its own build, ov-wasm-lite, with only what decrypting a share link needs: 191 KB gzipped.
The release profile is the usual: opt-level = "z", LTO, wasm-opt, and a size budget in CI that fails the build when a change makes it bigger.
KDBX: writing my own crate
Every vault is a KeePass (.kdbx) file, so the core needed a KDBX reader and writer. The obvious choice was keepass-rs. I ran a spike against a small corpus of files written by KeePassXC, kdbxweb, the iOS app and others, with a hard rule: nothing another app wrote may be lost.
keepass-rs opened every file and wrote files KeePassXC could open. But:
- An unknown child element of
<Group>made the whole file fail to open. Unknown children of<Meta>,<Entry>and<AutoType>were silently dropped on save. - String fields, custom data and deleted objects lived in
HashMaps, so their order changed on every save. - An absent
QualityCheckandQualityCheck=Truecouldn’t be told apart, so every entry gained the element.
None of that could be fixed from outside the crate. Fixing it inside meant replacing its XML layer and its model, which is most of the crate. So ov-kdbx is its own crate, using quick-xml’s pull reader, with an explicit unknown passthrough on every element that can have one, and the 2.3k-line Swift KDBX code as the map.
Proving it behaves the same
Swapping the crypto under three shipping apps is the kind of change you only get to get wrong once. Nothing switched to the core until it matched the old code byte for byte.
Test vectors. The TypeScript SDK was the reference. I recorded its behaviour as JSON vectors: key derivation, keyset wrapping, vault-key sealing, OPAQUE transcripts, share links, and merge cases. The Rust tests, the SDK’s tests on WASM, the Swift tests on UniFFI and the Qt tests on cxx all load the same files.
A libopaque transcript. Accounts registered on the desktop were created by libopaque, a different implementation. A recorded libopaque registration has to log in through opaque-ke, or desktop users would be locked out after the switch.
Merge fixtures recorded from the desktop. The desktop’s merge (inherited from KeePassXC) was the behaviour users already had, so its results were recorded as fixtures and the Rust merge has to reproduce them.
A real-world corpus. Every .kdbx in the corpus is opened, saved and compared, and the result has to open in KeePassXC.
Fuzzing. Eight cargo fuzz targets cover everything that reads untrusted bytes: the KDBX header, inner stream, key files, XML, the protocol JSON, share-link decoding and the server-sent events parser.
Cross-client end-to-end tests. Register on one client, sign in and sync on another, against a local copy of the real servers.
The fuzzers earned their keep. Later I wrote a faster XML tokenizer and writer, and kept quick-xml around as a reference: under fuzzing, every input goes through both and the outputs must match. That differential check found four bugs in the write-back path that had been there all along.
Performance
Moving the merge into Rust didn’t make it fast by itself. The first Rust merge of a 5,000-entry vault took 138 ms on an M3 Pro, because it found each entry’s counterpart by walking the tree. An index by UUID brought it to 31 ms.
A full local-edit sync of the same vault (decrypt, merge, re-encrypt) went from 297 ms to about 101 ms after three changes:
- caching the decrypted base copy between syncs instead of decrypting it every time,
- the faster XML reader (85.7 → 60.2 ms to read 5k entries),
- a direct XML writer, byte-identical to
quick-xml’s output (64 → 41.5 ms).
The budget is 300 ms on an iPhone 12. I haven’t measured that phone yet, so treat that as open.
Where it ended up
Every client now runs on the core:
- The TypeScript SDK went from ~7.9k lines of protocol code to a ~5.4k-line wrapper, and its next major version drops kdbxweb entirely.
- The iOS package went from ~10.1k to ~5.7k lines of Swift, most of it platform glue: Keychain, AutoFill, the Host.
- The desktop dropped libopaque, liboprf and libsodium from its build. Corrosion builds the core from a pinned commit, so distribution packagers can still build everything from source.
- The
ovCLI is a native Rust binary.
What’s still open: no tagged core release yet (each client pins an exact commit until 1.0.0), and the iPhone measurements.
If I did it again, I’d design the bindings around the domain model from day one, and I’d write the test vectors before writing any Rust. The vectors were the thing that made the whole move safe. Everything else was typing.
The code is at github.com/openvireo/openvireo-core.