API reference › @evolu/common › local‑first/Owner

Cryptographic identities that define ownership, encryption, sync, and deletion boundaries for Evolu data.

Every database change belongs to an Owner and is encrypted with its OwnerEncryptionKey. Owners also make sync selective: only the AppOwner is synced by default, while other owners can be synced when needed.

Individual changes in an append-only local-first history can only be marked as deleted. An entire owner, however, can be removed from devices and relays together with all of its data. The AppOwner must remain because it coordinates the deletion of other owners across devices.

Choose an owner by how its data should live and be shared:

• AppOwner coordinates sync and persists for the lifetime of the app identity.
• ShardOwner partitions application data so it can be synced and deleted independently.
• SharedOwner grants collaborative read and write access.
• SharedReadonlyOwner grants read-only access to shared data.

An OwnerSecret deterministically derives three independent values using SLIP-21:

• OwnerId: the public identifier.
• OwnerEncryptionKey: the symmetric key that protects the data.
• OwnerWriteKey: the rotatable token that authorizes writes.

Only holders of the encryption key can create an owner's changes. Each change is encrypted and authenticated together with its timestamp, so a relay, or anyone who can write to a relay for the owner, can store bytes for the owner but cannot forge or move a change. A client stores only the changes it can decrypt, verify, and decode, and syncs only what it stored. It skips any other change, which sync state shows on the route of the relay that holds it, and the relay offers it again on each sync until the client stores a valid change with that timestamp.

Core

Name	Description
Owner	An ReadonlyOwner with an OwnerWriteKey for authorizing writes.
OwnerError	Common interface implemented by all owner domain errors.
OwnerUsage	Storage usage and timestamp bounds for an Owner.
ReadonlyOwner	Owner without a OwnerWriteKey.
OwnerEncryptionKey	Symmetric encryption key for Owner data protection.
OwnerId	A branded Id that uniquely identifies an Owner.
OwnerIdBytes	Binary representation of OwnerId.
OwnerSecret	BIP-39 entropy used to derive Owner keys.
OwnerWriteKey	A token that authorizes write operations for an Owner.
OwnerEncryptionKey	Symmetric encryption key for Owner data protection.
OwnerId	A branded Id that uniquely identifies an Owner.
OwnerIdBytes	Binary representation of OwnerId.
OwnerSecret	BIP-39 entropy used to derive Owner keys.
OwnerWriteKey	A token that authorizes write operations for an Owner.
ownerWriteKeyLength	Length of an OwnerWriteKey in bytes.
createOwnerSecret	Creates a cryptographically random 32-byte OwnerSecret.
createOwnerWriteKey	Creates a random OwnerWriteKey for rotating write access.
mnemonicToOwnerSecret	Converts a Mnemonic to the OwnerSecret it represents.
ownerIdBytesToOwnerId	Converts OwnerIdBytes to OwnerId.
ownerIdToOwnerIdBytes	Converts OwnerId to OwnerIdBytes.
ownerSecretToMnemonic	Converts an OwnerSecret to a Mnemonic.

Variants

Name	Description
AppOwner	The AppOwner represents the application owner. It's created using a cryptographically secure random generator or derived from an external source, e.g., mnemonic stored securely in a hardware device.
DeviceAppOwner	An AppOwner for encrypting device-only data.
ShardOwner	An Owner for sharding data.
SharedOwner	An Owner for collaborative data with write access.
SharedReadonlyOwner	Read-only version of a SharedOwner for data sharing. Contains only the OwnerId and EncryptionKey needed for others to read the shared data without write access.
createAppOwner	Creates an AppOwner from an OwnerSecret.
createShardOwner	Creates a ShardOwner from an OwnerSecret.
createSharedOwner	Creates a SharedOwner from an OwnerSecret for collaborative write access.
createSharedReadonlyOwner	Creates a SharedReadonlyOwner from a SharedOwner.
deriveShardOwner	Derives a ShardOwner from an AppOwner using the specified path.

Transport

Name	Description
OwnerWebSocketTransport	WebSocket transport configuration.
SyncOwner	An ReadonlyOwner or Owner with non-empty OwnerTransports so it can be synced.
OwnerTransport	Transport configuration for connecting to relays.
createOwnerWebSocketTransport	Creates an OwnerWebSocketTransport for the given relay URL and OwnerId.
parseOwnerIdFromOwnerWebSocketTransportUrl	Extracts OwnerId from an OwnerWebSocketTransport URL query string.

Testing

Variable	Description
testAppOwner	Deterministic AppOwner for tests.
testOwnerSecret	Deterministic OwnerSecret for tests.