Skip to content New Self-host your password sync in 15 minutes Read more Menu Download OpenVireo

@openvireo/sdk 1.0 runs on the shared Rust core (@openvireo/core-wasm), the same code the iOS and desktop apps use. Crypto, OPAQUE, the session and tokens, the keyring, sync, KDBX and merge all happen in the core. The SDK is now a TypeScript layer over it.

Most of the account API is the same. What changed is everything that used to hand you a kdbxweb object: vaults are now the core’s Vault handle (to edit) or Kdbx handle (to merge and re-key). kdbxweb, hash-wasm and @noble/* are no longer dependencies.

Loading

The core loads synchronously the first time a function needs it. In Node, Bun and workers you don’t need to do anything. In a browser, call await ready() once at startup, so the full module (about 880 KB gzip) compiles before the first synchronous call:

import { ready } from "@openvireo/sdk";
await ready();

@openvireo/sdk/share uses only the lite module (about 190 KB gzip), so a public share page doesn’t load the rest. @openvireo/sdk/sync loads no WebAssembly at all. Every other entry (@openvireo/sdk, /crypto, /opaque, /auth, /vault, /merge) brings the full module into the bundle that imports it, so to keep it out of a page’s first load, import those with a dynamic import() when a vault or account is first needed (type imports are free):

const sdk = await import("@openvireo/sdk");
await sdk.ready();
const account = await sdk.Account.connect({ issuer });

Accounts

0.x1.0
account.auth (an AuthClient with its own tokens)account.auth is still an AuthClient, but it borrows the core’s access token
account.sync (SyncClient)gone: the core syncs. To call the sync server yourself, make a SyncClient with account.auth’s token
account.tokens (TokenManager), tokens.currentgone: account.signedIn, account.userId, account.email; account.core.accessToken(false) gives the token
alice.auth.createOrg, listMembers, listDevices, …still on account.auth (snake_case JSON), or account.core.createOrg, orgMembers, devices, … (camelCase records)
confirmMember(orgId, member) with auth.listMembers memberspass members from account.core.orgMembers(orgId) (userId, publicKeys). The core fetches and checks the keys itself
account.me()the core’s Profile (camelCase), which also has kdf (the keyset’s KDF parameters) and publicKeys (signature checked, with fingerprint). planOf(profile.plan) turns its plan into the 0.x Plan shape
share(vaultId, who, role), then show the fingerprint it returnsthe same; new: shareWithKeys(vaultId, who, role, keys) shares to the keys whose fingerprint the user confirmed beforehand, and fails with invalid_public_keys if they changed since
sealUnlocked output s1.…now s2.…. Seals made by 0.x don’t open, so after the upgrade, unlock once with the password
importVault(source: Kdbx, …)importVault(source: Vault, …)
subscribe({ onVaultChanged }) gets { type: "vault", id, etag }gets { kind: "vaultChanged", vaultId, etag, revision, deleted }
loadState, saveState, loadPending, savePending, deletePending, keepsOfflineDatagone: the offline cache belongs to the core

listVaults, reconnect, listShares, recoverInfo, recoveryStatus and deletionPreview return the same shapes as before. Two differences: recoveryStatus().locked only appears when it’s true, and wrong-key errors are vault_key_mismatch as before.

Sign-in errors say why. login and unlock still fail with unauthorized, and now set err.details.reason: "opaque_refused" (wrong email or password) or "keyset_unwrap_failed" (the password was accepted but the Secret Key doesn’t match; on an offline unlock, a wrong password). After keyset_unwrap_failed on login the core signs out the session it opened, so account.signedIn is false.

Storage. storage keeps the same key names (ov:session, secret_key:<server>:<email>, device:…, ov:parked_session:…), so signed-in sessions and trusted-device Secret Keys carry over. The offline cache uses a new format. Edits that a 0.x device made offline and never uploaded are not carried over, so let each device sync before upgrading. After the upgrade, vaults download again the first time they’re opened.

Accidental session ends keep unsynced edits. In 0.x, and in early 1.0 builds, any end of the session dropped the whole offline cache. Now, when the session ends by accident (onSignedOut reports session_expired or token_reused), each vault’s edits not yet uploaded stay (encrypted with the vault key) and sync after the same user signs in again. logout(), a revoked session and every other reason still drop everything.

One live session per storage. The core keeps the session in memory. Two Account instances on the same storage in one process can’t both refresh tokens (the server sees a reused refresh token and ends the session). Use one instance per storage, and connect a new one only after a reload.

Account vaults

import { addEntryToDb, setItemFields } from "@openvireo/sdk";

// 0.x: addEntryToDb(vault.db!, vault.db!.getDefaultGroup().uuid.toString(), …)
addEntryToDb(vault.vault, vault.vault.rootGroupId(), { title: "Db", username: "app", passwordValue: "s3cret", url: "", notes: "", tags: [] });
setItemFields(vault.vault, { groupPath: ["Apps"], entry: "Api" }, { token: "…" }, { create: true });
const report = await vault.sync();   // 0.x SyncResult → the core's SyncReport (outcome, conflicts, changes, clockOffsetMs)
  • vault.db (kdbxweb) is now vault.vault, the core’s Vault.
  • vault.sync({ rekeyTo }) is gone: account.rotate re-keys.
  • vault.sync({ acceptServerState: true }) continues after server_rolled_back or server_lost_database.
  • vault.info has the same shape. vault.etag and vault.offline are unchanged, and vault.readOnly is new.
  • Editing vault.vault while sync() runs is safe: the core merges those edits into the result and uploads them in the same call (up to two more rounds; anything later stays as unsynced edits for the next sync). 0.x and early 1.0 builds dropped them, so apps queued edits behind syncs; that queue is no longer needed for account vaults.
  • A pull (sync({ localChanged: false }) when another device changed the vault) reports pulled and uploads nothing. Early 1.0 builds sometimes uploaded once after merging an edit made in the same second.
  • Moves and deletes remember the group an entry or group left (PreviousParentGroup), so restoring from the Recycle Bin puts it back there instead of in the root. A file that uses this is saved as KDBX 4.1 (KeePassXC 2.7+ and KeePass 2.48+ read it; older KDBX 4 readers open it and ignore the element).
  • vault.vault.restoreEntry(version, id, groupPath) on an entry in the Recycle Bin keeps its history and moves it out of the bin (to its previous group, else groupPath).
  • revoke and rotate finish a rotation this account left half done; another account’s unfinished rotation is rotation_pending (409).

Local databases (@openvireo/sdk/vault)

0.x (kdbxweb)1.0
Kdbx = kdbxweb’s databaseVault (core handle) to edit; Kdbx (core handle) to merge, re-key, snapshot
openKdbx(bytes, credentials) → kdbxweb Kdbx (async)openLocalVault(bytes, credentials) → Vault; openKdbx(bytes, key) → Kdbx (sync)
kdbxweb.Kdbx.create(...), createNewKdbx(name, pw)createLocalVault(name, credentials), createNewKdbx(name, pw) (returns vault, not dbInstance)
saveKdbx(db) (async)vault.saveLocal(); saveKdbx(kdbx) (sync) for a Kdbx
decryptKdbx(...).dbInstancedecryptKdbx(...).vault
CredentialsFactory (passwordCredentials(pw)())plain { password?, keyFile? } bytes; passwordCredentials(pw) returns it directly
passwordHashCredentials(hash) (a kdbxweb CredentialsFactory)passwordHashCredentials(hash, keyFile?) → plain { passwordHash, keyFile? } credentials: openLocalVault, openKdbx, saveLocal and SelfHostedSync.syncDatabase all take them, so a database kept as its hash opens, saves and syncs without the password
addEntryToDb(db, groupUuid, data) → KdbxEntryaddEntryToDb(vault, groupId, data) → the new entry’s id
editEntryInDb, deleteEntryFromDb, createGroupInDb, … (async, kdbxweb objects)same names, synchronous, on a Vault, ids instead of objects
findEntryInKdbx, findGroupInKdbx, getUuidString, fieldText(value)vault.entry(id), vault.groups(); ids are hex; fieldText(entryRecord, name)
findEntry(db, ref) → KdbxEntryfindEntry(vault, ref) → EntryRecord
readField, writeField, setItemFields, itemOf, listItems on kdbxwebthe same on a Vault / EntryRecord
exportSelectedGroupsToKdbx(db, ids, pw) → ArrayBufferexportSelectedGroupsToKdbx(vault, ids, pw, kdf?) → Uint8Array
rekeyToVaultKey(db, key), copyKdbx, syncGeneration(db), dropServerRemotes(db), applyVaultKdf(db)methods on Kdbx: rekeyToVaultKey, clone, syncGeneration, dropServerRemotes, applyVaultKdf
kdfSettings(db)kdfSettings(bytes) (reads the outer header) or kdbx.kdfSettings()
initKdbx, kdbxwebgone

A wrong password, password hash or key file is vault_key_mismatch, as in 0.x, from openLocalVault, openKdbx, decryptKdbx and sync alike. (Early 1.0 builds reported kdbx_error from openLocalVault; that code now only means a file that isn’t valid KDBX.)

vault.exportPlain("csv" | "json", groupIds?) writes exactly the bytes the web app’s Export dialog writes: CSV with the unquoted header Folder,Title,Username,Password,URL,Notes, every value quoted (" doubled), lines joined by \n and no newline at the end; JSON as JSON.stringify(rows, null, 2) with the keys folder, title, username, passwordValue, url, notes in that order. folder is the name of the entry’s own group (not its path) and an empty title is (Untitled Entry). Early 1.0 builds quoted the header, ended the CSV with a newline, sorted the JSON keys and wrote the group path as folder.

Entry and group ids are the core’s: 32 lowercase hex digits. kdbxweb used base64 ids, so if you stored ids, convert them (base64 → bytes → hex).

Merge (@openvireo/sdk/merge)

import { kdbxMerge, mergeDatabases } from "@openvireo/sdk/merge";
import { openKdbx } from "@openvireo/sdk/vault";

const local = openKdbx(localBytes, { vaultKey });
const report = mergeDatabases(local, openKdbx(remoteBytes, { vaultKey }), openKdbx(baseBytes, { vaultKey }));
report.conflicts;   // 0.x: a Map of uuid → fields; now [{ uuid, title, fields }]
// or on bytes:
const merged = kdbxMerge(localBytes, remoteBytes, baseBytes, { vaultKey });
  • mergeDatabases is synchronous and returns { conflicts, added, updated, deleted, changes, localChanged, remoteChanged }.
  • mergeInto(source, target, mode) (KeePassXC’s Database > Merge), snapshotOf, needsCommonBase, findConflicts and hasPendingDeletions take Kdbx handles.
  • importInto(source, target) and importAsCopies(source, target, parentId) take Vaults. Their summary is the same. importInto now also brings the source’s database custom data items the target lacks (never KPXC_REMOTE_SYNC_SETTINGS or generated items); 0.x left all custom data behind.
  • fieldsOf, applyField, resolveFields, conflictingFields, combineEntries, sameFields, binaryBytes, findEntryByUuid, entrySeconds are gone. They worked on kdbxweb entries, and the core does all of that inside the merge.

Sync (@openvireo/sdk/sync)

  • syncKdbx, SyncState, serializeSyncState, deserializeSyncState are gone. Use vault.sync(), SelfHostedSync.syncDatabase, or account.core.syncVaultKdbx(vaultId, bytes, base) for an account vault you hold as a file.
  • SyncResult is now the core’s SyncReport. isClockSkewed and CLOCK_SKEW_WARNING_MS are unchanged.
  • SyncClient, SseParser and subscribeEvents are unchanged, for calling the sync server yourself.

Self-hosted (SelfHostedSync)

import { passwordCredentials } from "@openvireo/sdk";

// 0.x: server.syncDatabase("home", { db, credentials: passwordCredentials(pw) }) → { db, state, … }
const { kdbx, report } = await server.syncDatabase("home", bytes, passwordCredentials("pw"));
  • syncDatabase(id, { db, credentials, localChanged, acceptServerState }) is now syncDatabase(id, bytes, credentials, { localChanged, acceptServerState }). localChanged: false checks with a HEAD first and hands back bytes unchanged (outcome "unchanged") when the server is unchanged too; acceptServerState: true continues after server_rolled_back or server_lost_database. state is gone: the core keeps the ETag and base copy in the storage you passed to pair/restore/connect.
  • credentials can be passwordHashCredentials(hash), so a database reopened from its hash (after a page reload) syncs without asking for the password again.
  • new SelfHostedSync(url, token) is now SelfHostedSync.connect(url, token, opts).
  • New: download(id) fetches a database as the server has it (or null), without its password, for the first local copy. health() rejects with not_sync_server when the address isn’t a sync server (0.x reported the page’s own status code).
  • deviceToken and client are gone. serverUrl is a getter, and history and openVersion are new.
  • events({ onEvent }) is now events(onEvent, onError?) with the core’s event records.

Service accounts

ServiceAccount.fromToken, read, inject, write and listVaults are unchanged. openVault and pull return the core’s Vault, and edit(id, fn) hands fn a Vault. New on sa.core: vaultKdbxCredentials(vaultId) and syncVaultKdbx(vaultId, bytes, base), to hold a granted vault as a .kdbx file (as account.core has for accounts). sa.config and sa.auth/sa.sync are gone: use sa.issuer (or sa.core.serverConfig()).

These signatures are unchanged and now call the core. Removed:

  • nobleArgon2 (pure-JS Argon2). setArgon2Impl still replaces the AUK’s Argon2, and coreArgon2 is the default. Share passcodes always use the core’s.
  • The vendored opaque-wasm.js module and its @openvireo/sdk/vendor/opaque-wasm.js export. loadOpaque() now loads the core.

Renamed: the server’s vault JSON type in @openvireo/sdk/auth is VaultJson (it was Vault, which is now the core handle).

The SDK docs cover OpenVireo SDK, develop (54c2a02), last updated 21 November 2026. Found a mistake? Edit this page on GitHub.