Lock, unlock, and check vault status; export and import encrypted vault backups; persist vault state with snapshots.

How to Manage the Vault

This guide shows you how to manage the lifecycle of a Hyperauth vault — locking and unlocking, checking status, backing up and restoring, and persisting state to durable storage.

Check vault status

status returns the current state of the vault without modifying it:

const s = await client.status();

console.log(s.locked); // boolean — whether the vault is currently locked
console.log(s.did);    // string — the identity's DID if unlocked

If you only need to check the lock state:

const locked = await client.isLocked();

Lock the vault

Call lock to clear the decrypted key material from memory. The returned object includes the encrypted database bytes so you can persist them before discarding:

const result = await client.lock();

if (result.success && result.database) {
  localStorage.setItem('vault-db', JSON.stringify(Array.from(result.database)));
}

Unlock the vault

Pass the encrypted database bytes and the encryption key derived from the user's passkey authentication:

const dbBytes = new Uint8Array(JSON.parse(localStorage.getItem('vault-db')!));

const result = await client.unlock(dbBytes, encryptionKey);

if (!result.success) {
  console.error('Unlock failed:', result.error);
}

The encryptionKey is a hex string derived during key generation. If you did not store it separately, re-derive it by calling authenticatePasskey and passing the result through the key derivation step in the vault.

Export the vault

exportVault produces an encrypted binary backup of the entire vault — all accounts, credentials, and DID documents — protected with a user-supplied password. Returns a Uint8Array.

const backup = await client.exportVault({ password: 'correct-horse-battery' });

// Write to a file, upload to cloud storage, etc.
const blob = new Blob([backup], { type: 'application/octet-stream' });
const url = URL.createObjectURL(blob);

If the vault is locked when you call exportVault, the operation throws a PluginCallError. Unlock first.

Import a vault backup

importVault restores a vault from a backup produced by exportVault. Provide the raw bytes and the password used during export:

const fileBytes = new Uint8Array(await file.arrayBuffer());

const result = await client.importVault({
  data: fileBytes,
  password: 'correct-horse-battery',
});

if (result.success) {
  console.log(`Restored DID: ${result.did}`);
  console.log(`Accounts: ${result.accounts}, Credentials: ${result.credentials}`);
} else {
  console.error('Import failed:', result.error);
}

If the password is wrong or the file is corrupt, result.success is false and result.error describes the failure.

Check for a persisted vault

If your client was created with createClient (which sets up the core bridge), you can check whether a vault has been previously persisted to durable storage:

const exists = await client.hasPersistedVault();
if (!exists) {
  // First-time setup — no vault to restore
}

This method requires the core bridge. It returns false if the client was constructed without it.

Snapshot the vault to IPFS

snapshotVault pins the current vault state to IPFS via the relay service and returns a CID:

const result = await client.snapshotVault();

if ('cid' in result) {
  console.log('Snapshot CID:', result.cid);
} else {
  console.error('Snapshot failed:', result.error);
}

Force an immediate persistence write

The vault background worker persists on a schedule. To force an immediate write to durable storage:

const result = await client.persistNow();

if (!result.success) {
  console.error('Persist failed:', result.error);
}

Both snapshotVault and persistNow require the core bridge. They return error objects rather than throwing if the bridge is unavailable.

Backup and restore workflow

A complete backup/restore cycle:

// --- Backup ---
const backup = await client.exportVault({ password: userPassword });
await uploadToCloudStorage(backup); // your storage layer

// --- Restore ---
const bytes = await downloadFromCloudStorage();
const result = await client.importVault({ data: bytes, password: userPassword });

if (result.success) {
  // Vault is now live — proceed to unlock if needed
  await client.unlock(bytes, derivedEncryptionKey);
}

How to Manage the Vault

On this page