Class Account

Readonlyauth

Readonlyconfig

Readonlysync

Readonlytokens

email

• get email(): string | undefined

  Returns string | undefined

fingerprint

• get fingerprint(): string

  this account's public key fingerprint (to compare out of band)

  Returns string

offline

• get offline(): boolean

  True while the servers can't be reached and this account works from the offline cache (only with the offline option). Edits are kept and upload once a sync succeeds again.

  Returns boolean

principal

• get principal(): string

  Returns string

signedIn

• get signedIn(): boolean

  Returns boolean

unlocked

• get unlocked(): boolean

  Returns boolean

userId

• get userId(): string | undefined

  Returns string | undefined

changeEmail

• changeEmail(p: { code: string; email: string; password: string }): Promise<void>

  Email change, step 2: with the mailed code and the master password, registers OPAQUE again under the new email. The password is checked first by unwrapping the keyset, so a typo can't become the new login. Keys, Secret Key and vaults stay as they are.

  Parameters

  • p: { code: string; email: string; password: string }

  Returns Promise<void>

changePassword

• changePassword(
      p: {
          current: string;
          kdf?: Partial<Omit<KdfParams, "alg" | "salt">>;
          next: string;
      },
  ): Promise<void>

  Changes the master password (SPEC.md §16). The current one is checked by unwrapping the keyset; then OPAQUE is registered again and the same keyset is wrapped with the new AUK, so sealed vault keys keep working. The Secret Key stays the same. The server signs out the other devices.

  Parameters

  • p: {
        current: string;
        kdf?: Partial<Omit<KdfParams, "alg" | "salt">>;
        next: string;
    }

  Returns Promise<void>

confirmMember

• confirmMember(
      orgId: string,
      member: Member,
      vaults?: { id: string; role: VaultRole }[],
  ): Promise<Member>

  Confirms an accepted member (owner/admin) after checking their key signature. Owners and admins get every org vault this account manages, with manage, and the org's SA master keys; a member gets the vaults in vaults only.

  Parameters

  • orgId: string
  • member: Member
  • vaults: { id: string; role: VaultRole }[] = []

  Returns Promise<Member>

createServiceAccount

• createServiceAccount(
      orgId: string,
      p: {
          expiresAt?: string | null;
          name: string;
          secretName?: string;
          vaults?: { id: string; role: VaultRole }[];
      },
  ): Promise<{ serviceAccount: ServiceAccount; token: string }>

  Creates a service account in an org (owner/admin): generates its keyset and master key in this client, seals the master key to every owner and admin, grants it the given vaults, and returns the token to show once.

  Parameters

  • orgId: string
  • p: {
        expiresAt?: string | null;
        name: string;
        secretName?: string;
        vaults?: { id: string; role: VaultRole }[];
    }

  Returns Promise<{ serviceAccount: ServiceAccount; token: string }>

createVault

• createVault(name: string, opts?: { orgId?: string }): Promise<AccountVault>

  Creates a vault (personal, or in an org with orgId; owners/admins are sealed in automatically).

  Parameters

  • name: string
  • opts: { orgId?: string } = {}

  Returns Promise<AccountVault>

importVault

• importVault(
      source: Kdbx,
      opts?: { name?: string; orgId?: string },
  ): Promise<AccountVault>

  "Move to account": copies an open database (local, or synced with a self-hosted server), re-keys the copy to a fresh vault key, creates the vault (personal, or in an org this account manages, sealed to every confirmed owner and admin) and uploads it with If-None-Match: *. The original is never changed. As in Qt, the copy's root group takes the vault name (default: the root group's name) and its sync server remotes are dropped. If the vault was created but the upload failed, a VaultUploadError carries the vault, whose sync() uploads it later.

  Parameters

  • source: Kdbx
  • opts: { name?: string; orgId?: string } = {}

  Returns Promise<AccountVault>

issueServiceAccountSecret

• issueServiceAccountSecret(
      saId: string,
      p?: { expiresAt?: string | null; name?: string },
  ): Promise<{ id: string; prefix: string; token: string }>

  Issues another secret for an SA (owner/admin): unseals the master key and builds a token to show once.

  Parameters

  • saId: string
  • p: { expiresAt?: string | null; name?: string } = {}

  Returns Promise<{ id: string; prefix: string; token: string }>

listVaults

• listVaults(): Promise<VaultInfo[]>

  GET /vaults: every vault this account can open, with names decrypted. With offline, an unreachable server falls back to the list from the last successful call.

  Returns Promise<VaultInfo[]>

lock

• lock(): void

  Clears private keys and vault keys from memory (best effort).

  Returns void

login

• login(
      p: {
          email: string;
          password: string;
          secretKey?: string;
          totp?: string | TotpPrompt;
          trustDevice?: boolean;
      },
  ): Promise<void>

  OPAQUE login (+ TOTP when the account has it), then unlock. The Secret Key is needed the first time on a device; with trustDevice (default) it is kept in storage for next time.

  Parameters

  • p: {
        email: string;
        password: string;
        secretKey?: string;
        totp?: string | TotpPrompt;
        trustDevice?: boolean;
    }

  Returns Promise<void>

logout

• logout(opts?: { forgetDevice?: boolean }): Promise<void>

  Revokes this device's session on the server and forgets it locally (the trusted Secret Key stays unless forgetDevice).

  Parameters

  • opts: { forgetDevice?: boolean } = {}

  Returns Promise<void>

onSignedOut

• onSignedOut(listener: (reason: SignedOutReason) => void): () => void

  Parameters

  • listener: (reason: SignedOutReason) => void

  Returns () => void

openVault

• openVault(vaultId: string): Promise<AccountVault>

  Opens a vault: downloads and decrypts it (newest key first). With offline, an unreachable server falls back to the copy this device kept (local edits not yet uploaded, else the server's copy at the last sync), and the vault's offline is true; a vault never synced here fails with not_available_offline.

  Parameters

  • vaultId: string

  Returns Promise<AccountVault>

reconnect

• reconnect(): Promise<{ dropped: string[]; vaults: VaultInfo[] }>

  Goes back online after working from the offline cache: re-reads the account record and the vault list. Vaults that are no longer listed (access revoked or the vault deleted meanwhile) are forgotten with their local copies and returned in dropped. Throws while still unreachable.

  Returns Promise<{ dropped: string[]; vaults: VaultInfo[] }>

recover

• recover(
      p: {
          kdf?: Partial<Omit<KdfParams, "alg" | "salt">>;
          password: string;
          token: string;
          trustDevice?: boolean;
      },
  ): Promise<{ secretKey: string; userId: string }>

  Resets the account with an approved ov_rc_ token (SPEC.md §18): a new Secret Key, KDF salt and keyset exactly as register makes them, a new OPAQUE record under the account email, and the old keys and vaults archived for 30 days on the server. Afterwards this device is signed in and unlocked and keeps the new Secret Key like after register; every other device is signed out. Returns the new Secret Key to show once (Emergency Kit). Errors as recoverInfo.

  Parameters

  • p: {
        kdf?: Partial<Omit<KdfParams, "alg" | "salt">>;
        password: string;
        token: string;
        trustDevice?: boolean;
    }

  Returns Promise<{ secretKey: string; userId: string }>

recoverInfo

• recoverInfo(token: string): Promise<RecoveryReset>

  What an approved reset will do (SPEC.md §18), for the {web}/?view=recover#token= page. Works signed out. Throws recovery_not_ready (409, err.details.notBefore) before the link starts working, recovery_cancelled (410) after a cancel, and session_expired (410) once used or expired.

  Parameters

  • token: string

  Returns Promise<RecoveryReset>

recoveryStatus

• recoveryStatus(): Promise<RecoveryStatus>

  Whether a recovery archive from a reset exists, until when, and whether it is locked (SPEC.md §18).

  Returns Promise<RecoveryStatus>

register

• register(
      p: {
          email: string;
          kdf?: Partial<Omit<KdfParams, "alg" | "salt">>;
          password: string;
          trustDevice?: boolean;
      },
  ): Promise<{ secretKey: string; userId: string }>

  Creates an account. Returns the Secret Key to show once (Emergency Kit). Signs in and unlocks.

  Parameters

  • p: {
        email: string;
        kdf?: Partial<Omit<KdfParams, "alg" | "salt">>;
        password: string;
        trustDevice?: boolean;
    }

  Returns Promise<{ secretKey: string; userId: string }>

removeMember

• removeMember(
      orgId: string,
      userId: string,
  ): Promise<{ failed: { error: unknown; id: string }[]; rotated: string[] }>

  Removes a member, then rotates every org vault the server flagged (rotation_required) that this account manages, so the old key opens nothing new. Failed rotations are returned, not thrown.

  Parameters

  • orgId: string
  • userId: string

  Returns Promise<{ failed: { error: unknown; id: string }[]; rotated: string[] }>

requestEmailChange

• requestEmailChange(email: string): Promise<void>

  Email change, step 1 (SPEC.md §16): the server mails an 8-digit code to the new address.

  Parameters

  • email: string

  Returns Promise<void>

restoreFromArchive

• restoreFromArchive(
      p: { oldPassword: string; oldSecretKey: string },
  ): Promise<{ restored: number }>

  Restores the vaults archived by a reset into the current keys (SPEC.md §18), with the old master password and the old Secret Key (the old Emergency Kit). Needs the account unlocked. OPAQUE login against the archived record (idU = the archived email the server returns), then the old keyset is unwrapped locally, each archived vault key re-sealed to the current enc_pk, and the proof signed with the old signing key. The old keys are wiped afterwards and the vault list reloaded.

  Errors: 401 unauthorized for a wrong old password; invalid_secret_key (local, before anything is restored) when the old Secret Key doesn't open the archived keyset; restore_locked (403); invalid_proof (400); session_expired (410); not_found (404) when there is no archive; forbidden (403) when the server wants a fresh sign-in.

  Parameters

  • p: { oldPassword: string; oldSecretKey: string }

  Returns Promise<{ restored: number }>

revoke

• revoke(vaultId: string, principals: string[]): Promise<SyncResult>

  Removes members and rotates the vault key in one step (SPEC §7).

  Parameters

  • vaultId: string
  • principals: string[]

  Returns Promise<SyncResult>

rotate

• rotate(vaultId: string, opts?: { remove?: string[] }): Promise<SyncResult>

  Rotation (SPEC §7): new key sealed to every remaining member → POST keys (removes remove at once) → download, re-key, conditional PUT (merge/retry on 412) → activate.

  Parameters

  • vaultId: string
  • opts: { remove?: string[] } = {}

  Returns Promise<SyncResult>

secretKey

• secretKey(): Promise<string | null>

  The Secret Key kept on this device, to download the Emergency Kit again. Needs the account unlocked.

  Returns Promise<string | null>

setMemberRole

• setMemberRole(orgId: string, member: Member, role: OrgRole): Promise<Member>

  Changes a member's org role. Promoting a confirmed member to owner/admin also hands over the SA master keys and manage on every org vault this account manages; the server drops their master keys on a demotion to member.

  Parameters

  • orgId: string
  • member: Member
  • role: OrgRole

  Returns Promise<Member>

share

• share(
      vaultId: string,
      who: { email?: string; principal?: string },
      role: VaultRole,
  ): Promise<{ fingerprint: string; principal: string }>

  Grants (or changes) access: seals the current vault key to the grantee after checking their keys.

  Parameters

  • vaultId: string
  • who: { email?: string; principal?: string }
  • role: VaultRole

  Returns Promise<{ fingerprint: string; principal: string }>

subscribe

• subscribe(
      handlers?: {
          onError?: (e: unknown) => void;
          onVaultChanged?: (
              e: {
                  deleted?: boolean;
                  etag?: string;
                  id: string;
                  revision?: number;
                  type: "vault";
              },
          ) => void;
          onVaultsChanged?: (vaults: VaultInfo[]) => void;
      },
  ): EventStream

  Live updates: vault events are passed on; on access events the JWT is refreshed (new vlt claims), the vault list reloaded and the stream reconnected (SPEC §11).

  Parameters

  • handlers: {
        onError?: (e: unknown) => void;
        onVaultChanged?: (
            e: {
                deleted?: boolean;
                etag?: string;
                id: string;
                revision?: number;
                type: "vault";
            },
        ) => void;
        onVaultsChanged?: (vaults: VaultInfo[]) => void;
    } = {}

  Returns EventStream

unlock

• unlock(password: string, secretKey?: string): Promise<void>

  Unlocks a signed-in (resumed) session with the master password; no OPAQUE round trip needed. With offline, an unreachable server falls back to the wrapped keyset cached at the last sign-in or unlock, so the password and Secret Key still have to be right.

  Parameters

  • password: string
  • OptionalsecretKey: string

  Returns Promise<void>

verifiedPublicKeys

• verifiedPublicKeys(principal: string): Promise<PublicKeys>

  Public keys of a principal, verified (sig) before anything is sealed to them.

  Parameters

  • principal: string

  Returns Promise<PublicKeys>

webSessionUrl

• webSessionUrl(next?: string): Promise<string>

  A one-time link (valid 60 seconds) that signs the browser in to the auth website and opens next, a path there such as /settings (SPEC.md §16).

  Parameters

  • Optionalnext: string

  Returns Promise<string>

Staticconnect

• connect(opts: AccountOptions): Promise<Account>

  Discovers the server and loads a stored session, if any (signed in but locked). With offline, an unreachable server falls back to the discovery document from the last successful connect.

  Parameters

  • opts: AccountOptions

  Returns Promise<Account>