Skip to content
OpenVireoDeveloper
GitHub

Hosted accounts

Sign up, sign in, unlock and lock, sessions and storage.

Account is the entry point for anything a person does with their OpenVireo account: signing up and in, unlocking, opening vaults, sharing. See Concepts for what the keys and secrets are.

import { Account } from "@openvireo/sdk";
const account = await Account.connect({
issuer: "https://accounts.openvireo.com", // discovery: /.well-known/openvireo-configuration
device: { name: "Firefox on Linux", platform: "web" },
storage: browserStorage(), // where sessions and trusted-device keys live
});

connect reads the issuer’s discovery document to find the account and sync servers, then loads a stored session if storage has one. A resumed session is signed in but locked (account.signedIn is true, account.unlocked false): the keys need the master password again.

device.platform is one of web, cli, connect, qt-linux, qt-macos, qt-windows, ios. Device lists can also show android (Android apps). The name shows up in the user’s device list.

storage keeps the session (refresh token, device id), the trusted device’s Secret Key, and each vault’s sync state. Pick one for the platform:

Storage Where Use it for
browserStorage() IndexedDB, encrypted with a non-extractable WebCrypto key browsers
new FileStorage(path) from @openvireo/sdk/storage/node a JSON file with mode 0600 Node and Bun tools
new MemoryStorage() (the default) memory tests, one-off scripts

Anything with get, set and delete (the KeyValueStorage interface) works, and EncryptedStorage wraps another storage with an AES-GCM key you provide.

const { secretKey, userId } = await account.register({ email, password });
showEmergencyKit(secretKey); // the only time the Secret Key is shown; the user must keep it

register makes the Secret Key and keyset on the device, registers OPAQUE, and leaves the account signed in and unlocked. With trustDevice (the default) this device keeps the Secret Key for next time. Later, account.secretKey() returns the kept copy, so the user can download the Emergency Kit again.

await account.login({
email,
password,
secretKey, // only needed the first time on this device
totp: () => askForCode(), // asked only when the account has two-factor authentication on
});

totp can be a code or a function, which is called again (with attempt and the last error) when a code is wrong. A missing code throws mfa_required, too many wrong ones mfa_expired.

Without secretKey on a device that doesn’t trust this account yet, login throws invalid_secret_key: ask for the Secret Key and try again. Pass trustDevice: false on shared computers.

if (account.signedIn && !account.unlocked) await account.unlock(password);
account.lock(); // wipes the keys from memory; the session stays
await account.logout(); // ends the session on the server and forgets it here
await account.logout({ forgetDevice: true }); // also forgets the trusted Secret Key

unlock needs no OPAQUE round trip: it unwraps the keyset with the password and the kept Secret Key.

A web app loses its memory on every reload. To unlock again without the master password, seal the unlocked keyset under a non-extractable WebCrypto key and keep the two apart: the key in IndexedDB, the sealed string somewhere that ends with the tab, such as sessionStorage.

const key = await crypto.subtle.generateKey({ name: "AES-GCM", length: 256 }, false, ["encrypt", "decrypt"]);
await saveKey(key);
sessionStorage.setItem("unlocked", await account.sealUnlocked(key));
// after the reload, on a connected (signed-in, locked) account
const sealed = sessionStorage.getItem("unlocked");
if (sealed) await reloaded.resumeUnlocked(sealed, await loadKey());

The seal is bound to this issuer and user. resumeUnlocked checks the unsealed keys against the account’s public keys (from /me, or offline the cached profile). It fails with signed_out when the session has ended, decryption_failed for a seal the key can’t open, and invalid_public_keys when the account’s keys changed (an account reset). lock() doesn’t revoke a seal, so delete the string and the key when your app locks.

The session can also end on its own: when the refresh token expires, is revoked from another device, or is used twice (token_reused, a sign of a stolen token). Listen for it:

const stop = account.onSignedOut((reason) => { // "session_expired" | "token_reused" | "unauthorized" | "logout"
showSignIn();
});

After session_expired or token_reused (an accident, not a sign-out), edits this device hadn’t uploaded yet are kept and sync once the same user signs in again. Every other reason, and logout(), drops them with the rest of the offline cache.

account.email; // the signed-in email
account.userId;
account.fingerprint; // this account's public key fingerprint, for others to compare
await account.changePassword({ current, next }); // signs the other devices out
await account.requestEmailChange("new@example.com"); // mails a code to the new address
await account.changeEmail({ email: "new@example.com", code, password });
const url = await account.webSessionUrl("/settings"); // a one-time link into the account website (60 s)

Changing the password keeps the same Secret Key and keyset, so vaults and shares keep working.

Deleting is scheduled (SPEC §23): the account is locked at once and erased after a grace period (30 days on the hosted service), when its personal vaults, keys and billing go too. Until then the user can sign in and restore it.

const preview = await account.deletionPreview();
preview.eraseOn; // when it would be erased
preview.vaults; // { id, name, sharedWith }: shared vaults can be given away first
preview.orgs; // outcome "leave", "delete" (deleted with the account) or "blocked"
if (preview.vaults[0]?.sharedWith.length) await account.transferVault(preview.vaults[0].id, bobPrincipal);
const { scheduledFor } = await account.deleteAccount({ password, confirm: typedEmail });
// This device is signed out (onSignedOut reports "deletion_scheduled") and its offline cache is gone.
// The Secret Key stays so the user can sign in again and restore:
if (account.deletionScheduledFor) await account.restoreAccount({ password });
  • A blocked org is one where the user is the only confirmed owner and others are in it. deleteAccount fails with deletion_blocked until the user makes one of members an owner (setMemberRole; admins need no new keys) or deletes the org.
  • Signed in to a pending account, deletionScheduledFor is the erase date and every vault call fails with account_pending_deletion. Show a screen with Restore and Sign out.
  • Other signed-in devices hear deletion_scheduled on the event stream and are signed out the same way.
  • Keep the date with your remembered-accounts list (SPEC §21) and remove the account, with forgetDevice, once deletionExpired(date) is true.

The lower-level account.auth (an AuthClient) covers every account server route, for things Account has no helper for, such as the device list and two-factor setup:

const { devices } = await account.auth.listDevices(); // name, platform, last_seen_at, current, …
const old = devices.find((d) => !d.current && d.name === "Old laptop");
if (old) await account.auth.revokeDevice(old.id);