Skip to content
OpenVireoDeveloper
GitHub

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.

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.

Releases are published to GitHub Packages. Installing from there needs a GitHub token with read:packages, even though the packages are public:

Terminal window
echo "@openvireo:registry=https://npm.pkg.github.com" >> .npmrc
echo "//npm.pkg.github.com/:_authToken=\${GITHUB_TOKEN}" >> .npmrc
npm install @openvireo/sdk

The 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.

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.

  • 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:api builds it locally)

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)

MIT OR Apache-2.0, at your option.