@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.x | 1.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.current | gone: 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 members | pass 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 returns | the 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, keepsOfflineData | gone: 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 nowvault.vault, the core’sVault.vault.sync({ rekeyTo })is gone:account.rotatere-keys.vault.sync({ acceptServerState: true })continues afterserver_rolled_backorserver_lost_database.vault.infohas the same shape.vault.etagandvault.offlineare unchanged, andvault.readOnlyis new.- Editing
vault.vaultwhilesync()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) reportspulledand 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, elsegroupPath).revokeandrotatefinish a rotation this account left half done; another account’s unfinished rotation isrotation_pending(409).
Local databases (@openvireo/sdk/vault)
| 0.x (kdbxweb) | 1.0 |
|---|---|
Kdbx = kdbxweb’s database | Vault (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(...).dbInstance | decryptKdbx(...).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) → KdbxEntry | addEntryToDb(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) → KdbxEntry | findEntry(vault, ref) → EntryRecord |
readField, writeField, setItemFields, itemOf, listItems on kdbxweb | the same on a Vault / EntryRecord |
exportSelectedGroupsToKdbx(db, ids, pw) → ArrayBuffer | exportSelectedGroupsToKdbx(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, kdbxweb | gone |
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 });
mergeDatabasesis synchronous and returns{ conflicts, added, updated, deleted, changes, localChanged, remoteChanged }.mergeInto(source, target, mode)(KeePassXC’s Database > Merge),snapshotOf,needsCommonBase,findConflictsandhasPendingDeletionstakeKdbxhandles.importInto(source, target)andimportAsCopies(source, target, parentId)takeVaults. Their summary is the same.importIntonow also brings the source’s database custom data items the target lacks (neverKPXC_REMOTE_SYNC_SETTINGSor generated items); 0.x left all custom data behind.fieldsOf,applyField,resolveFields,conflictingFields,combineEntries,sameFields,binaryBytes,findEntryByUuid,entrySecondsare gone. They worked on kdbxweb entries, and the core does all of that inside the merge.
Sync (@openvireo/sdk/sync)
syncKdbx,SyncState,serializeSyncState,deserializeSyncStateare gone. Usevault.sync(),SelfHostedSync.syncDatabase, oraccount.core.syncVaultKdbx(vaultId, bytes, base)for an account vault you hold as a file.SyncResultis now the core’sSyncReport.isClockSkewedandCLOCK_SKEW_WARNING_MSare unchanged.SyncClient,SseParserandsubscribeEventsare 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 nowsyncDatabase(id, bytes, credentials, { localChanged, acceptServerState }).localChanged: falsechecks with aHEADfirst and hands backbytesunchanged (outcome"unchanged") when the server is unchanged too;acceptServerState: truecontinues afterserver_rolled_backorserver_lost_database.stateis gone: the core keeps the ETag and base copy in thestorageyou passed topair/restore/connect.credentialscan bepasswordHashCredentials(hash), so a database reopened from its hash (after a page reload) syncs without asking for the password again.new SelfHostedSync(url, token)is nowSelfHostedSync.connect(url, token, opts).- New:
download(id)fetches a database as the server has it (ornull), without its password, for the first local copy.health()rejects withnot_sync_serverwhen the address isn’t a sync server (0.x reported the page’s own status code). deviceTokenandclientare gone.serverUrlis a getter, andhistoryandopenVersionare new.events({ onEvent })is nowevents(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()).
Crypto, OPAQUE, share links
These signatures are unchanged and now call the core. Removed:
nobleArgon2(pure-JS Argon2).setArgon2Implstill replaces the AUK’s Argon2, andcoreArgon2is the default. Share passcodes always use the core’s.- The vendored
opaque-wasm.jsmodule and its@openvireo/sdk/vendor/opaque-wasm.jsexport.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.