The core for the JVM and Android: accounts, vaults, sync, share links and .kdbx files, on the same
Rust code as the iOS, desktop and web apps. UniFFI generates the Kotlin API (package
com.openvireo.core) from bindings/ov-ffi, and JNA loads it. The
artifact also has:
- ready-made Host parts (
com.openvireo.core.hosts), so a program needs no glue; - a Java API without coroutines (
com.openvireo.core.java), where everysuspendmethod returns aCompletableFuture.
| Artifact | For | Natives |
|---|---|---|
com.openvireo:openvireo-core-jvm | Kotlin and Java 11+ on macOS, Linux and Windows | darwin-aarch64, darwin-x86-64, linux-x86-64, linux-aarch64, win32-x86-64 in the jar; JNA picks the right one |
com.openvireo:openvireo-core-android | Android 8.0+ (minSdk 26) | libov_ffi.so for arm64-v8a, armeabi-v7a, x86_64 |
Both depend on JNA 5 and kotlinx-coroutines-core. The version is the core’s version. The build and
developer notes are in bindings/kotlin.
Install
The artifacts are on GitHub Packages. GitHub Packages asks for a token even for public packages, so
every consumer needs a GitHub personal access token (classic) with the read:packages scope. This
goes away once the artifacts are on Maven Central.
Keep the token out of the build file. Put it in ~/.gradle/gradle.properties:
gpr.user=your-github-login
gpr.key=ghp_...
Gradle (settings.gradle.kts or build.gradle.kts):
repositories {
mavenCentral()
maven {
url = uri("https://maven.pkg.github.com/openvireo/openvireo-core")
credentials {
username = providers.gradleProperty("gpr.user").orElse(providers.environmentVariable("GITHUB_ACTOR")).get()
password = providers.gradleProperty("gpr.key").orElse(providers.environmentVariable("GITHUB_TOKEN")).get()
}
}
}
dependencies {
implementation("com.openvireo:openvireo-core-jvm:X.Y.Z") // or openvireo-core-android
}
In GitHub Actions, give the job permissions: packages: read. If GITHUB_TOKEN is still refused
(401 or 403), use a PAT stored as a secret instead.
Maven: add the token to ~/.m2/settings.xml:
<settings>
<servers>
<server>
<id>openvireo</id>
<username>your-github-login</username>
<password>ghp_...</password>
</server>
</servers>
</settings>
and the repository and dependency to pom.xml. The <id> must match:
<repositories>
<repository>
<id>openvireo</id>
<url>https://maven.pkg.github.com/openvireo/openvireo-core</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>com.openvireo</groupId>
<artifactId>openvireo-core-jvm</artifactId>
<version>X.Y.Z</version>
</dependency>
</dependencies>
Kotlin
Every call that touches the network or storage is a suspend function and takes a CancelToken.
Local work is synchronous: reading and editing an open vault, and the crypto functions.
import com.openvireo.core.*
import com.openvireo.core.hosts.defaultHost
import kotlinx.coroutines.runBlocking
import java.nio.file.Path
fun main() = runBlocking {
val client = OvClient(
ClientConfig(DeviceInfo(id = null, name = "backup tool", platform = Platform.CLI), offline = false, server = null),
defaultHost(cacheDir = Path.of("ov-cache")),
)
val account = signIn(client, "[email protected]", ask("Master password: ").toByteArray())
for (info in account.vaults(CancelToken())) {
val vault = account.openVault(info.id, CancelToken())
for (entry in vault.entries(false)) { // false: leave out the Recycle Bin
println("${info.name} / ${entry.groupPath.joinToString("/")} ${entry.title} ${entry.username}")
}
}
}
DeviceInfo.nameis what the account’s device list shows. Programs on the JVM usePlatform.CLI.offline = truekeeps the offline cache: unlock, list and open vaults without the network, and keep edits until they upload. It needs a persistentBlobCache(defaultHost(cacheDir = ...)).serveris a discovery document to use instead of fetching one. Leave itnull.- Every generated object is
AutoCloseable:close()(oruse { }) frees its native handle now instead of when it is garbage-collected.
Sign in
suspend fun signIn(client: OvClient, email: String, password: ByteArray): Account {
val account = client.connect("https://accounts.openvireo.com", CancelToken())
if (account.isSignedIn()) {
// A stored session (persistent SecureStore): unlock it, no OPAQUE round trip.
account.unlock(password, null, CancelToken())
return account
}
val input = LoginInput(email, password, secretKey = null, totp = null, trustDevice = true)
var step = try {
account.login(input, CancelToken())
} catch (e: OvException) {
if (e.code != OvErrorCode.INVALID_SECRET_KEY) throw e
// A new device: the Secret Key isn't stored here yet.
account.login(input.copy(secretKey = ask("Secret Key: ").toByteArray()), CancelToken())
}
while (step is LoginStep.NeedsTotp) {
step = try {
account.submitTotp(step.challenge, ask("Two-step code: "), CancelToken())
} catch (e: OvException) {
if (e.code != OvErrorCode.INVALID_MFA) throw e // mfa_expired: start again
step
}
}
return account
}
ask stands for however your program prompts (print(prompt); readln()).
connectfetches the server’s discovery document and loads a stored session if there is one. The account is then signed in but locked, andunlockopens it with the master password.- A device that has never seen the account doesn’t have the Secret Key.
loginwithout one fails withinvalid_secret_key. Ask for the key and try again. WithtrustDevice = truethe core keeps it in theSecureStore. - A wrong password, or an email with no account, is
unauthorized. A wrong Secret Key is alsounauthorized, withdetails{"reason": "keyset_unwrap_failed"}instead of"opaque_refused". - Two-step sign-in returns
LoginStep.NeedsTotp. A wrong code isinvalid_mfaand the same challenge takes another (challenge.attempt()counts the tries). After the fifth wrong code, or once the challenge expires, the result ismfa_expiredand the sign-in starts again. account.signOut(forgetDevice, CancelToken())ends the session and deletes the offline cache, including edits that haven’t synced.
Add an entry, sync, share
val vault = account.openVault(vaultId, CancelToken())
val entryId = vault.addEntry(
vault.ensureGroup("Servers/Prod"), // or vault.rootGroupId()
EntryInput(
fields = listOf(
FieldInput("Title", "Router".toByteArray(), null),
FieldInput("UserName", "admin".toByteArray(), null),
FieldInput("Password", "correct horse".toByteArray(), null),
),
removeFields = emptyList(),
tags = null,
iconId = null,
expiry = EntryExpiry.Keep,
),
)
val report = vault.sync(SyncOptions(localChanged = true), CancelToken())
val payload = itemSharePayload(vault.entry(entryId), defaultShareFields(), null)
val share = account.createShare(payload, ShareOptions(3600u, 1u, null, vault.id(), entryId), CancelToken())
println(share.url.decodeToString())
- Edits stay in the local copy until
sync.localChanged = trueuploads them, after merging in what other devices uploaded.localChanged = falseonly pulls. entry(id)gives the full record. Field values areByteArray(UTF-8 for text).find("ov://Vault/Group/Title")andreadField("ov://Vault/Group/Title/Password")look an entry or a field up by reference.share.urlis aByteArray, because it holds the link’s key. To open a link without an account, callclient.shareInfo(api, parseShareLink(link).id, ...), thenclient.openShare(api, link, null, info, ...), whereapiisaccount.serverConfig().api.
Errors
Everything throws OvException. It has one variant, OvException.Failure, and extensions in
com.openvireo.core read its fields without a cast:
try {
account.login(input, CancelToken())
} catch (e: OvException) {
when (e.code) {
OvErrorCode.UNAUTHORIZED -> println("wrong email, password or Secret Key")
OvErrorCode.NETWORK_ERROR -> println("offline: ${e.errorMessage}")
OvErrorCode.RATE_LIMITED -> println("try again in ${e.retryAfter}s")
else -> println("${e.wireCode} (${e.status}): ${e.errorMessage}")
}
}
| Field | |
|---|---|
code | an OvErrorCode |
wireCode | the stable string ("unauthorized"). It’s the server’s own code when that isn’t one of OvErrorCode. |
errorMessage | English text for logs. e.message is a summary of every field. |
status | the HTTP status (Int?) |
retryAfter | seconds (Long?), for RATE_LIMITED |
(e as OvException.Failure).details | a JSON object string with camelCase keys |
(e as OvException.Failure).serverCode | the server’s code when it isn’t one of OvErrorCode |
The codes are the TypeScript SDK’s, one for one, plus internal. The SDK’s
error list says what each one
means.
Coroutines and cancellation
- Call the
suspendfunctions from any coroutine and any dispatcher. They don’t block the calling thread. - Cancelling the calling coroutine drops the core’s future, and with it the Host call in
progress. The coroutine gets a
CancellationException. - A
CancelToken: callingcancel()from any thread makes every call that holds the token fail withOvExceptioncodeABORTED. One token can be shared by several calls. Once cancelled, a token stays cancelled. - The synchronous functions do CPU work in the core. For a big vault, call them off the main thread.
Names that differ from Swift
Every generated object is AutoCloseable (close() frees the handle), and exceptions are
Throwables, which already have a message. So a few members have other names in Kotlin and Java:
| Swift / Python | Kotlin and Java |
|---|---|
EventStream.close() | EventStream.closeStream() |
ByteStream.close() (a Host stream) | ByteStream.closeStream() |
ServiceAccount.close() | ServiceAccount.endSession() |
OvError.Failure.message | OvException.Failure.errorMessage |
TransportError.Tls/Other.message | TransportException.Tls/Other.reason |
close() on those objects frees the native handle. It doesn’t end the stream or the session.
Java
com.openvireo.core.java is the whole API for Java. It’s in the same jar and AAR.
import com.openvireo.core.*;
import com.openvireo.core.java.*;
import java.nio.charset.StandardCharsets;
import java.nio.file.Path;
import java.util.List;
import java.util.concurrent.CompletionException;
JOvClient client = new JOvClient(
new ClientConfig(new DeviceInfo(null, "backup tool", Platform.CLI), false, null),
JDefaultHosts.create(Path.of("ov-cache")));
JAccount account = client.connect("https://accounts.openvireo.com").join();
LoginInput input = new LoginInput(email, password, null, null, true);
LoginStep step;
try {
step = account.login(input).join();
} catch (CompletionException e) {
if (JErrors.code(e) != OvErrorCode.INVALID_SECRET_KEY) throw e;
input.setSecretKey(askSecretKey());
step = account.login(input).join();
}
while (step instanceof LoginStep.NeedsTotp) {
JTotpChallenge challenge = new JTotpChallenge(((LoginStep.NeedsTotp) step).getChallenge());
step = account.submitTotp(challenge, askCode()).join();
}
for (VaultInfo info : account.vaults().join()) {
JVault vault = account.openVault(info.getId()).join();
for (EntrySummary entry : vault.entries(false)) {
System.out.println(info.getName() + " / " + entry.getTitle() + " " + entry.getUsername());
}
}
JVault vault = account.openVault(vaultId).join();
List<FieldInput> fields = List.of(
new FieldInput("Title", "Router".getBytes(StandardCharsets.UTF_8), null),
new FieldInput("Password", "correct horse".getBytes(StandardCharsets.UTF_8), null));
String entryId = vault.addEntry(vault.rootGroupId(),
JRecords.newEntryInput(fields, List.of(), null, null, EntryExpiry.Keep.INSTANCE));
vault.sync(new SyncOptions(true, false)).join();
SharePayload payload = JOv.itemSharePayload(vault.entry(entryId), JOv.defaultShareFields(), null);
CreatedShare share = account.createShare(payload,
JRecords.newShareOptions(3600L, 1L, null, vault.id(), entryId)).join();
- Wrappers.
JOvClient,JAccount,JVault,JServiceAccount,JSelfHosted,JEventStreamandJTotpChallengewrap the generated objects. Objects come back wrapped. To wrap one you got from a record, usenew JTotpChallenge(step.getChallenge()).unwrap()gives the generated object, andclose()frees it. Records, enums,CancelTokenandHostare the generated types and need no wrapper. - Futures. Each
suspendmethod returnsCompletableFuture<T>(CompletableFuture<Void>when there’s no result). Synchronous methods are plain calls and declarethrows OvExceptionwhere the core can fail. - No
CancelTokenneeded. Each method that takes aCancelTokenhas an overload without it.future.cancel(true)then cancels the call: the coroutine, the core’s future and the Host call in progress. Pass a token to cancel several calls together, and they fail withABORTED. JOvhas every free function as a static: the crypto primitives, share links, TOTP, OPAQUE, and the wire codes.- Unsigned numbers. Kotlin hides constructors and getters that use unsigned types from Java. In
Java they become the next wider signed type (
UIntbecomeslong,UShortbecomesint), and values going in are range-checked. Records that have unsigned fields are built withJRecords.new<Record>(...)and read withJRecords.get<Field>(record), for exampleJRecords.newShareOptions(3600L, 2L, null, null, null),JRecords.newKdfOverrides(19456L, 2L, 1L)andJRecords.getOpensLeft(info). - Records with defaults need every argument from Java:
new SyncOptions(true, false).
Errors in Java
A future fails with OvException. join() wraps it in CompletionException, and get() in
ExecutionException. JErrors unwraps either one and returns null for any other exception:
try {
account.login(input).join();
} catch (CompletionException e) {
OvErrorCode code = JErrors.code(e);
if (code == OvErrorCode.UNAUTHORIZED) {
System.out.println("wrong email, password or Secret Key");
} else if (code == null) {
throw e; // not from the core
} else {
System.out.println(JErrors.wireCode(e) + " " + JErrors.status(e) + ": " + JErrors.errorMessage(e));
}
}
JErrors also has retryAfter, details, serverCode and ovException(e).
Threads
Futures run on JScope.defaultScope(), a SupervisorJob on Dispatchers.Default. Each wrapper
constructor also takes an Executor (or a CoroutineScope), and objects it returns use the same one:
JOvClient client = new JOvClient(config, host, Executors.newFixedThreadPool(4));
Don’t call join() inside a Host part. The part runs on the core’s threads, and blocking there can
deadlock.
The Host
The core never opens a socket or a file, reads the clock or touches a keychain. It calls a Host
made of five parts, and defaultHost(...) (Kotlin) or JDefaultHosts (Java) fills in all of them:
| Part | JVM default | Android default | Others shipped |
|---|---|---|---|
HttpTransport | JavaNetHttpTransport | UrlConnectionTransport | UrlConnectionTransport on the JVM |
SecureStore | MemoryStore | MemoryStore | none |
BlobCache | FileCache(cacheDir), or MemoryCache without a directory | FileCache(noBackupFilesDir/openvireo-cache) | MemoryCache |
Clock | SystemClock | SystemClock | |
LogSink | JulLogSink (java.util.logging, loggers openvireo.<module>) | AndroidLogSink (logcat, tag OpenVireo) |
defaultHost(cacheDir = Path.of("ov-cache"), store = MyKeychainStore()) // Kotlin, JVM
Host host = JDefaultHosts.builder().store(myKeychainStore).cache(new FileCache(Path.of("ov-cache"))).build();
MemoryStore keeps nothing between runs, so each run is a new device: it signs in from scratch and
needs the Secret Key. To keep sessions and trusted Secret Keys, write a SecureStore over the OS
keychain, or over the Android Keystore on Android. No keychain store ships yet.
The cache holds only ciphertext and public data (vault blobs encrypted under the vault key, the wrapped keyset, the discovery document).
Transports
JavaNetHttpTransport(JVM only) is built onjava.net.http.HttpClient. It’s fully async and streams the server’s events. Its client is built withRedirect.NEVERand noCookieHandler. If you pass your ownHttpClient(for a proxy or custom TLS), build it the same way, or the constructor refuses it.requestTimeout(60 s) bounds the wait for response headers.UrlConnectionTransportis built onHttpURLConnectionand runs onDispatchers.IO. It works everywhere, but has two caveats on the desktop JVM:- The JVM’s own
HttpURLConnectioncan’t sendPATCH, and the core uses PATCH to rename organisations, vaults and service accounts. Those calls fail withTransportException.Other. Android’sHttpURLConnection(OkHttp underneath) sends PATCH. HttpURLConnectionalways uses the process-wideCookieHandler. If anything in the process callsCookieHandler.setDefault(...), this transport sends and stores cookies, which the core’s contract forbids. UseJavaNetHttpTransportin such a process.
- The JVM’s own
Writing a part
In Kotlin, implement the generated interfaces (HttpTransport, SecureStore, BlobCache with
suspend methods; Clock and LogSink plain). In Java, implement JHttpTransport, JSecureStore and
JBlobCache, which return futures, and build the Host with JHosts.create(http, store, cache, clock, log)
or JHosts.builder(). Clock and LogSink are functional interfaces, so lambdas work:
Host host = JHosts.create(myTransport, myStore, myCache, System::currentTimeMillis, (level, target, msg) -> {});
JHosts.fromKotlin(new JavaNetHttpTransport()) turns a shipped Kotlin part into its Java
interface, so you can decorate it.
The rules:
- Threads. The core calls Host parts from its own threads, in coroutines on
Dispatchers.Default. Do blocking I/O insidewithContext(Dispatchers.IO) { ... }in Kotlin, or complete the future from your own executor in Java. Never block aDispatchers.Defaultthread. - A transport must not follow redirects, must not store or send cookies, must send the core’s
headers as given, and must return every HTTP status as a response. It throws
TransportException(Offline,Timeout,Tls(reason),Other(reason)) only when there’s no response. - A store or cache returns
nullfor a missing key. When it can’t read or write, it throwsovException(OvErrorCode.INTERNAL, "why")(Kotlin,com.openvireo.core.hosts), or completes the future withJErrors.ovException(code, message)(Java). - Anything else thrown reaches the core as a network error (from a transport) or
internal. - Never log request headers: they carry bearer tokens.
Android
dependencies {
implementation("com.openvireo:openvireo-core-android:X.Y.Z")
}
import com.openvireo.core.*
import com.openvireo.core.hosts.defaultHost
val client = OvClient(
ClientConfig(DeviceInfo(id = null, name = Build.MODEL, platform = Platform.ANDROID), offline = true, server = null),
defaultHost(applicationContext),
)
From Java: new JOvClient(config, JDefaultHosts.create(context)).
Call the
suspendfunctions fromlifecycleScopeorviewModelScope. They never block the main thread. Keep the synchronous ones, such asVault.entrieson a big vault, off the main thread.The app needs the
INTERNETpermission.Cache location.
defaultHost(context)puts the offline cache innoBackupFilesDir/openvireo-cache. That directory is app-private and not backed up, and the system doesn’t clear it. Don’t usecontext.cacheDir: the system clears it when storage is low, which drops the offline copy and any edits not yet synced. PasscacheDir =to choose another directory.ABIs. The AAR has the core for
arm64-v8a,armeabi-v7aandx86_64. JNA’s AAR also bringsarmeabi,x86,mipsandmips64. Limit the app to the three ABIs, or it installs on anx86device (an old emulator) and fails when the core loads:android { defaultConfig { ndk { abiFilters += listOf("arm64-v8a", "armeabi-v7a", "x86_64") } } }R8 / ProGuard. JNA finds native methods, structures and callbacks by reflection. The AAR ships consumer rules that keep
com.sun.jna.**andcom.openvireo.core.**, and they apply automatically. You don’t need to add anything.Size. About 1.5 to 1.8 MiB of compressed native code per ABI. A Play Store app bundle delivers one ABI per device. The build notes have the measurements.
Secrets
Passwords, Secret Keys and field values cross into the JVM as ByteArray, and Kotlin Strings you
make from them can’t be wiped at all. The core zeroizes its own copies. The JVM can’t guarantee that
for yours: call fill(0) (Arrays.fill(a, (byte) 0)) on arrays you no longer need, and avoid turning
secrets into Strings. Records’ toString() prints their fields, so don’t log records that hold
secrets.
Self-hosted servers
- Your own account server: pass its issuer URL to
connect. It must behttps://. Loopback (http://localhost:8000) is the one exception, and any otherhttp://URL fails withinsecure_url. - A standalone sync server (paired devices, no account):
SelfHosted.pair(client, url, code, deviceName, CancelToken()), laterrestoreSelfHosted(client, url), thensyncDatabase(id, kdbxBytes, credentials, CancelToken()). In Java, useJSelfHosted.pair(...)andJOv.restoreSelfHosted(...). The pairing token is kept in theSecureStoreand the sync state in theBlobCache, so both must persist. - Service accounts (
ov_sa_...tokens):ServiceAccount.fromToken(client, token, CancelToken())(JServiceAccount.fromTokenin Java). Thenvaults,read("ov://Vault/Entry/Field"),writeandinject.endSession()wipes its keys and cached vaults from memory, and later calls fail withsigned_out.
The examples are tested
DocsSamplesTest (Kotlin) and JavaDocsSamplesTest (Java) in bindings/kotlin/core-jvm/src/test run the
samples on this page against the in-memory servers (cargo xtask kotlin --smoke).
The Core bindings docs cover OpenVireo core, develop (bcbf55a), last updated 21 November 2026. Found a mistake? Edit this page on GitHub.