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.
Connecting
Section titled “Connecting”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
Section titled “Storage”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.
Signing up
Section titled “Signing up”const { secretKey, userId } = await account.register({ email, password });showEmergencyKit(secretKey); // the only time the Secret Key is shown; the user must keep itregister 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.
Signing in
Section titled “Signing in”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.
Unlocking and locking
Section titled “Unlocking and locking”if (account.signedIn && !account.unlocked) await account.unlock(password);
account.lock(); // wipes the keys from memory; the session staysawait account.logout(); // ends the session on the server and forgets it hereawait account.logout({ forgetDevice: true }); // also forgets the trusted Secret Keyunlock needs no OPAQUE round trip: it unwraps the keyset with the password and the kept Secret Key.
Staying unlocked across a page reload
Section titled “Staying unlocked across a page reload”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) accountconst 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.
The account itself
Section titled “The account itself”account.email; // the signed-in emailaccount.userId;account.fingerprint; // this account's public key fingerprint, for others to compare
await account.changePassword({ current, next }); // signs the other devices outawait account.requestEmailChange("new@example.com"); // mails a code to the new addressawait 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 the account
Section titled “Deleting the account”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 erasedpreview.vaults; // { id, name, sharedWith }: shared vaults can be given away firstpreview.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
blockedorg is one where the user is the only confirmed owner and others are in it.deleteAccountfails withdeletion_blockeduntil the user makes one ofmembersan owner (setMemberRole; admins need no new keys) or deletes the org. - Signed in to a pending account,
deletionScheduledForis the erase date and every vault call fails withaccount_pending_deletion. Show a screen with Restore and Sign out. - Other signed-in devices hear
deletion_scheduledon 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, oncedeletionExpired(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);