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.
Sync loop
Section titled “Sync loop”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.
HTTP clients
Section titled “HTTP clients”AuthClienthas a method for every account server route.account.authis one signed in with the account’s session: it borrows the core’s access token (the core refreshes it).TokenManageris for anAuthClientyou run without anAccount.SyncClientcovers every sync server route:vault(id)anddatabase(id)return blob handles withget,head,put,delete,historyandgetRevision, andsubscribeEventsopens 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.
Vaults and KDBX
Section titled “Vaults and KDBX”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
Section titled “Argon2”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 core modules
Section titled “The core modules”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).