OpenVireo SDK
The packages, installing, and a first program.
TypeScript code for building on OpenVireo: sign in to an account, open and edit vaults, share them, run
service accounts in CI, or sync with a self-hosted sync server. It is the same code the OpenVireo web app,
the ov CLI, ov connect and the GitHub Action run, and it interoperates with the desktop app: the same
crypto, the same OPAQUE suite, the same merge.
Everything is end-to-end encrypted on the client. The servers only ever receive OPAQUE messages,
encrypted .kdbx files, wrapped keysets and sealed keys; see Concepts.
Packages
Section titled “Packages”| Package | What it is |
|---|---|
@openvireo/sdk |
The library: accounts, vaults, sharing, sync, merge, service accounts |
@openvireo/cli |
ov: read, inject and rotate secrets from scripts and CI. See CLI |
@openvireo/connect |
ov connect: a REST server for one service account, with Kubernetes manifests. See Connect |
| GitHub Action | Loads secrets into a workflow and masks them. See GitHub Action |
The SDK runs in browsers, Node ≥ 20 and Bun (also compiled into a single binary). It’s ESM only.
Install
Section titled “Install”Releases are published to GitHub Packages. Installing from there needs a GitHub token with read:packages,
even though the packages are public:
echo "@openvireo:registry=https://npm.pkg.github.com" >> .npmrcecho "//npm.pkg.github.com/:_authToken=\${GITHUB_TOKEN}" >> .npmrcnpm install @openvireo/sdkThe ov CLI and the openvireo-connect server are command-line programs: download them as signed single
binaries from the releases (no Node needed); see
CLI and Connect.
A first program
Section titled “A first program”import { Account, MemoryStorage } from "@openvireo/sdk";
const account = await Account.connect({ issuer: "https://accounts.openvireo.com", device: { name: "My script", platform: "cli" }, storage: new MemoryStorage(),});await account.login({ email, password, secretKey });
for (const info of await account.listVaults()) { console.log(info.name, info.role);}const vault = await account.openVault((await account.listVaults())[0]!.id);console.log(vault.read("ov://Personal/GitHub/username"));await account.logout();For automation, prefer a service account: it needs no password and can be limited to a few vaults.
Guides
Section titled “Guides”- Hosted accounts: sign up, sign in, unlock, lock, devices, storage
- Vaults and sharing: open, read, write, create, share, revoke, organisations
- Live updates: react to changes from other devices and to access changes
- Offline: keep working without the network
- Moving a database to an account
- Account recovery: resets and restoring the old vaults
- Share links: give an item or some text to someone without an account
- Service accounts: CI, servers and long-running processes
- Self-hosted sync servers: no account, just a sync server
- Testing your app: the in-memory servers
Reference
Section titled “Reference”- Concepts: keys, vaults, roles, references, what the servers see
- Errors: every error code and what to do about it
- Merge behaviour: how concurrent edits are combined
- Lower-level APIs: the sync loop, HTTP clients, vaults and KDBX, Argon2, the core modules
- Migrating to 1.0: from 0.x (kdbxweb) to the core’s handles
- API reference: every export, generated from the source
(
npm run docs:apibuilds it locally)
Subpath imports
Section titled “Subpath imports”Everything is exported from @openvireo/sdk. Smaller entry points keep bundles small:
| Subpath | What it contains |
|---|---|
@openvireo/sdk/crypto |
Secret Key, AUK (Argon2id), wrap/seal, keysets, fingerprints, vault names, SA and refresh tokens, JWT verification |
@openvireo/sdk/opaque |
The OPAQUE client (opaque-ke, in the shared core) |
@openvireo/sdk/auth |
AuthClient (every account server route), discovery, TokenManager, storage adapters |
@openvireo/sdk/storage/node |
FileStorage (a 0600 JSON file) |
@openvireo/sdk/sync |
SyncClient, subscribeEvents, sync results and the clock-skew check |
@openvireo/sdk/vault |
The core’s Vault and Kdbx handles, credentials, entry helpers, ov:// references |
@openvireo/sdk/merge |
The sync merge and .kdbx import, matching the desktop app |
@openvireo/sdk/share |
Opening share links without an account, share payloads, TOTP codes (loads only the core’s lite module) |
@openvireo/sdk/testing |
In-memory auth and sync servers for tests (not for production) |
License
Section titled “License”MIT OR Apache-2.0, at your option.