Vaults and sharing
Open, read and write vaults; create, share, revoke; organisations.
All of this needs an unlocked Account.
Listing and opening
Section titled “Listing and opening”const vaults = await account.listVaults();// [{ id, name, role: "read" | "write" | "manage", orgId, currentKeyVersion, pendingKeyVersion, rotationRequired }]
const vault = await account.openVault(vaults[0]!.id); // downloads and decrypts itvault.name;vault.vault; // the core `Vault` handle: entries, groups, fields, history, attachmentsvault.etag; // the server version this copy is based onNames are decrypted on the device. openVault tries the newest key the account holds first and falls back
to the previous one, so a vault in the middle of a key rotation still opens.
Reading and writing fields
Section titled “Reading and writing fields”vault.read("ov://Team/GitHub/password");vault.read({ groupPath: ["Apps"], entry: "Stripe", field: "username" });
await vault.write("ov://Team/GitHub/password", "new value"); // edits and syncsawait vault.write("ov://Team/Apps/Stripe/api_key", key, { create: true }); // creates the entry if neededSee Concepts for how references find entries. write keeps the previous
version in the entry’s history and stores password and custom fields protected.
Editing the database directly
Section titled “Editing the database directly”vault.vault is the shared Rust core’s Vault handle. Edit it (addEntry, editEntry, setFields,
moveEntry, addGroup, setAttachment, …, or the SDK’s plain-data helpers), then call sync():
import { addEntryToDb, setItemFields } from "@openvireo/sdk";
addEntryToDb(vault.vault, vault.vault.rootGroupId(), { title: "Database", username: "app", passwordValue: "s3cret", url: "", notes: "", tags: [],});setItemFields(vault.vault, { groupPath: ["Apps"], entry: "Api" }, { username: "svc", token: "…" }, { create: true });
const result = await vault.sync();result.outcome; // "uploaded", "pulled" (only downloaded), "created" or "unchanged"result.conflicts; // entries both sides changed: { uuid, kind, title, fields }result.changes; // what the merge did, entry by entrysync() downloads the server copy, merges it with your changes against the last common version, and
uploads the result with If-Match. When another device uploaded in between, it merges again and retries (up
to five times, then too_many_conflicts; your changes stay in vault.vault). See
Merge behaviour.
Call vault.sync({ localChanged: false }) to only pick up changes from elsewhere: it asks the server with a
HEAD first and downloads nothing when the version hasn’t moved.
Editing vault.vault while a sync runs is safe: the core merges those edits into the sync’s result and
uploads them in up to two more rounds of the same call. Edits that land after that stay as unsynced edits
(vault.vault.hasPendingEdits()) for the next sync.
Creating vaults
Section titled “Creating vaults”const personal = await account.createVault("Personal");const team = await account.createVault("Team Infra", { orgId }); // org owners and admins get manage automaticallycreateVault makes the vault key, registers the vault with the account server, and uploads an empty database
whose root group has the vault’s name. It returns the opened vault.
Sharing
Section titled “Sharing”const { principal, fingerprint } = await account.share(vaultId, { email: "bob@example.com" }, "write");await confirmWithBob(fingerprint); // compare it with what Bob's app shows, out of band
await account.share(vaultId, { principal }, "read"); // changing the roleshare looks up the person’s public keys, checks their signature, seals the vault key to them and grants the
role. It needs manage on the vault. The other person needs an account already.
To have the user compare the fingerprint before anything is sealed, look the person up first and share to
the keys they confirmed. If the keys changed in between (the person reset their account), shareWithKeys
seals nothing and fails with invalid_public_keys:
import { fingerprint, trustedPublicKeys } from "@openvireo/sdk";
const bob = await account.auth.lookupUser("bob@example.com");const keys = trustedPublicKeys(bob); // throws invalid_public_keys if the signature doesn't verifyawait confirmWithBob(fingerprint(keys));await account.shareWithKeys(vaultId, { principal: bob.principal }, "write", keys);Revoking and rotating
Section titled “Revoking and rotating”await account.revoke(vaultId, [bobPrincipal]); // removes access and rotates the vault key in one stepawait account.rotate(vaultId); // a new key without removing anyoneRotating makes a new vault key, seals it to everyone who stays, re-encrypts the file with it and then makes it
current. Access is removed on the server first, so the removed person can’t download the re-encrypted
file. Their old downloads still open with the old key, so change the secrets inside if that matters. A vault
whose rotationRequired is true (someone left the organisation) should be rotated by a manager.
A rotation that stopped half way (the app closed before the new key was made current) is finished by the
next revoke or rotate from the same account, before its own rotation. Another account’s unfinished
rotation blocks it with rotation_pending (409) until that one is finished or, after 24 hours, replaced.
Organisations
Section titled “Organisations”Organisations are managed through the account server API on account.auth, with helpers on Account for
the steps that need keys:
const org = await account.auth.createOrg("Acme");await account.auth.invite(org.id, { email: "carol@example.com", role: "member" });// Carol gets an email, and her app calls account.auth.acceptInvitation(invitationToken)
const { members } = await account.auth.listMembers(org.id);const carol = members.find((m) => m.email === "carol@example.com" && m.status === "accepted")!;await account.confirmMember(org.id, carol, [{ id: "<vault id>", role: "read" }]); // seals vault keys to her
await account.setMemberRole(org.id, carol, "admin"); // admins get manage on every org vaultconst { rotated, failed } = await account.removeMember(org.id, carol.user_id); // and rotates her vaults(await account.auth.me()).orgs lists the organisations the account belongs to.