kestrove-core/README.md

Kestrove core

This is the heart of Kestrove, the self-hosted password manager. Everything that touches your secrets lives here, in one Rust codebase that every app shares:

• the encryption (your master password and Secret Key turn into the keys that lock your vault),
• the vault itself (logins, passkeys, one-time codes, notes, cards, tags, "Sign in with Google"…),
• sync with your Kestrove server, and the merging of changes made on two devices at once,
• passkeys (creating and signing them), one-time codes, the password generator,
• import from 1Password and CSV, and encrypted export.

Because all apps use this same code, a vault works the same on iPhone, Mac, Android, Windows, Linux and in the browser, and the security-critical parts are written and reviewed once.

You only need this repository to build the apps or to work on Kestrove itself. To run a server, see kestrove-server.

How the apps use it

App	How it gets the core
iPhone, iPad, Mac (kestrove-apple)	scripts/build-apple.sh builds a Swift package
Android (kestrove-android)	scripts/build-android.sh builds the native libraries and Kotlin bindings
Windows and Linux (kestrove-desktop)	Uses the Rust code directly
Web vault (kestrove-web)	crates/kv-wasm/build.sh builds a WebAssembly package (kestrove-web keeps a copy)
Server (kestrove-server)	Uses only the shared message formats (kv-proto); it never handles secrets

Keep the repositories side by side in one folder (kestrove-core, kestrove-apple, …): the apps find the core by that relative path.

Build and test

You need Rust (install it once from rustup.rs):

cargo test --workspace --all-features     # every test
cargo clippy --workspace --all-targets --all-features

Build for the apps:

./scripts/build-apple.sh       # → ../kestrove-apple/Packages/KestroveCore  (needs Xcode)
ANDROID_NDK_HOME=~/Library/Android/sdk/ndk/27.3.13750724 ./scripts/build-android.sh
                               # → ../kestrove-android/core-ffi            (needs the Android NDK and cargo-ndk)
(cd ../kestrove-web && scripts/vendor-core.sh)
                               # → builds kv-wasm and copies it into the web vault (needs wasm-pack)

Run these again after changing the core, so the apps pick up the change.

Test against a real server (start a fresh local kestrove-server first; the test file explains how):

cargo test -p kv-ffi --test live_server -- --ignored

What's inside

Crate	What it does
kv-crypto	Keys and encryption: turning the master password and Secret Key into keys (Argon2id), sealing every item (XChaCha20-Poly1305), sealing vault keys for devices (HPKE), signatures (Ed25519).
kv-model	Vault items and what's in them, website matching (which login belongs to which site), one-time codes (TOTP), passkey signing (WebAuthn), the password generator.
kv-store	The encrypted copy of the vault kept on each device (SQLite). It stores only ciphertext.
kv-sync	Talking to the server: login without sending the password (OPAQUE), signed requests, pulling and pushing changes, merging edits from two devices, and a signed summary that catches a server hiding or rolling back data.
kv-proto	The message formats shared with the server. No secrets.
kv-ffi	The one API every app calls (VaultCore): create an account, unlock, read and save items, passkeys, sync, add devices. Also the browser bridge that the Mac and desktop apps use to answer the browser extension.
kv-wasm	The same API for the web vault, as WebAssembly in a Web Worker.
kv-import	Import from 1Password (.1pux) and CSV, and passphrase-encrypted export (.kvex).
kv-ipc, kv-nmh	The small helper (kestrove-nmh) that browsers start to reach the Kestrove app, and its local connection to the app.

The design behind all this, with the reasons, is in kestrove-spec: start with docs/02-cryptography.md and docs/03-sync-protocol.md.

Rules for changes

• No unsafe code outside the generated bindings.
• Secrets are kept in Zeroizing<…> so they're wiped from memory, and are never logged or printed.
• Changing a stored or transmitted format? Change the spec first, then add test vectors to kestrove-spec/vectors (cargo run -p kv-crypto --example gen-vectors writes them).
• No GPL dependencies (the apps go to the App Store); cargo deny check must pass.