Browser client basics

Understand browser initialization, Result values, lock state, encryption contexts, Recovery Kits, and the normal application lifecycle.

Initialize once

This page covers @ownfold/browser. For server methods and backend-only use, read Vault server.

Call initialize() when using the headless browser client directly. React’s VaultProvider performs initialization after hydration. Initialization inspects remote vault metadata and local IndexedDB state, then returns a discriminated vault state; it does not create a vault without an explicit user action.

Handle fallible operations

Ownfold returns Result values for expected failures:

const result = await vault.encryptJson(input)
if (result.status === "error") {
  renderVaultError(result.error.code, result.error.message)
  return
}
await repository.save(result.value)

Do not catch and discard these errors. Codes are stable for application logic; messages are safe for humans and do not include key bytes, passwords, or ciphertext.

Bind every record to context

namespace, recordId, vaultId, keyVersion, and optional ownerId are authenticated. Use a stable namespace per record family and the same immutable record ID on encryption and decryption. Changing a database primary key without migrating the envelope context makes decryption fail by design.

Lock behavior

When locked, root-key access is removed from the active crypto engine and record operations return VaultLockedError. Locking coordinates across same-origin tabs. Automatic locking reduces exposure after inactivity but cannot protect against malicious JavaScript already executing while unlocked.

Recovery behavior

Recovery Kit creation and verification are local. The password or generated recovery code never enters a transport request. Restoration registers the current browser as a device only after the root key has been recovered locally. Losing all devices and the Recovery Kit permanently loses the data.

Where to go next

Read architecture, React integration, and the security guidance. Framework and database sections contain complete mounting and migration instructions.