Skip to content
OpenVireoDeveloper
GitHub

Lower-level APIs

The sync loop, HTTP clients, KDBX helpers, Argon2 and OPAQUE.

Account, ServiceAccount and SelfHostedSync are built from smaller pieces, all exported. Use them when you need control the high-level classes don’t give, for example your own storage of sync state, or the sync loop over files that aren’t vaults.

The sync loop is the shared Rust core’s (ov-sync): vault.sync() on an account vault, syncDatabase on a self-hosted server, or account.core.syncVaultKdbx(vaultId, bytes, base) for an account vault you hold as a file. Each does a HEAD when nothing changed locally (vault.sync({ localChanged: false }), syncDatabase(id, bytes, credentials, { localChanged: false })), a download, the rollback checks (revision and the sync generation inside the file), the three-way merge against the base copy kept in the offline cache, the If-Match upload, and on 412 download, merge and retry (up to five times, then too_many_conflicts). Since 1.0 there is no syncKdbx; see Migrating to 1.0.

report.clockOffsetMs is how far this computer’s clock is ahead of the sync server’s (negative: behind), from the server’s Date header; it is undefined when the server sent none the client could read (a browser needs the server to list Date in Access-Control-Expose-Headers). Sync decides edits and deletions against the base copy, not by clocks, but a wrong clock still stamps entries with wrong times and breaks TOTP codes, so warn when isClockSkewed(report.clockOffsetMs) (off by more than CLOCK_SKEW_WARNING_MS, 5 minutes), as the desktop and iOS apps do.

mergeDatabases(local, remote, base) is the merge on its own, on Kdbx handles (openKdbx(bytes, key)), and kdbxMerge(local, remote, base, key) the same on file bytes; see Merge behaviour. Like the desktop app, it applies permanent deletions only with the base: an item deleted on one side goes from both unless the other side changed it since the base. Deleting to the Recycle Bin is a move and syncs normally.

  • AuthClient has a method for every account server route. account.auth is one signed in with the account’s session: it borrows the core’s access token (the core refreshes it). TokenManager is for an AuthClient you run without an Account.
  • SyncClient covers every sync server route: vault(id) and database(id) return blob handles with get, head, put, delete, history and getRevision, and subscribeEvents opens the events stream.

Every client takes fetch (any fetch-compatible function, default globalThis.fetch) and headers to add to every request, such as a User-Agent in Node.

A database is the core’s Vault handle: openLocalVault(bytes, credentials), createLocalVault(name, credentials), vault.saveLocal(), and the entry, group, field, history and attachment methods on it. credentials are { password?, keyFile? } as bytes; passwordCredentials(password) and vaultCredentials(vaultKey) make them. The web app’s plain-data helpers work on a Vault: decryptKdbx, createNewKdbx, collectAllDbData, addEntryToDb, editEntryInDb (history first), deleteEntryFromDb, group helpers and exportSelectedGroupsToKdbx. For references and items: parseReference, readField, writeField, findEntry, parseItemReference, itemOf, listItems and setItemFields. Entry and group ids are 32 lowercase hex digits.

The lower-level file handle is Kdbx (openKdbx, createVaultKdbx, openWithKeyVersions, saveKdbx, rekeyToVaultKey, merge, importFrom, snapshot, …), which @openvireo/sdk/merge works with.

Argon2 (all three types, any output length) runs on the core’s lite module. At m = 64 MiB, t = 3 it takes about 110 ms (Node 24, M-series Mac), as fast as the hash-wasm build 0.x used. setArgon2Impl(fn) replaces it for the AUK (for example with a native binding in Node); coreArgon2 is the default.

The SDK calls @openvireo/core-wasm, openvireo-core compiled to WebAssembly, in two modules: the lite one (primitives, share links, TOTP; about 190 KB gzip) and the full one (everything else, about 880 KB gzip). Both load synchronously the first time they’re needed. In a browser, await ready() once at startup so the full module compiles before the first synchronous call. @openvireo/sdk/share loads only the lite module, so a public share page stays small. OPAQUE is in the full module (opaque-ke 4.0.1, the same suite as the account server and the desktop app).