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. Owners are meant to be the unit of real deletion: an entire owner removed from devices and relays together with all of its data, while the AppOwner remains to coordinate the deletion of other owners across devices. Evolu doesn't implement owner deletion yet.

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 independently and, once Evolu implements owner deletion, 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:

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

NameDescription
OwnerAn ReadonlyOwner with an OwnerWriteKey for authorizing writes.
OwnerErrorCommon interface implemented by all owner domain errors.
OwnerUsageStorage usage of an Owner.
ReadonlyOwnerOwner without a OwnerWriteKey.
OwnerEncryptionKeySymmetric encryption key for Owner data protection.
OwnerIdA branded Id that uniquely identifies an Owner.
OwnerIdBytesBinary representation of OwnerId.
OwnerSecretBIP-39 entropy used to derive Owner keys.
OwnerWriteKeyA token that authorizes write operations for an Owner.
OwnerEncryptionKeySymmetric encryption key for Owner data protection.
OwnerIdA branded Id that uniquely identifies an Owner.
OwnerIdBytesBinary representation of OwnerId.
OwnerSecretBIP-39 entropy used to derive Owner keys.
OwnerWriteKeyA token that authorizes write operations for an Owner.
ownerWriteKeyLengthLength of an OwnerWriteKey in bytes.
createOwnerSecretCreates a cryptographically random 32-byte OwnerSecret.
createOwnerWriteKeyCreates a random OwnerWriteKey. A relay that already stores another write key for the owner rejects it, as OwnerWriteKey describes.
mnemonicToOwnerSecretConverts a Mnemonic to the OwnerSecret it represents.
ownerIdBytesToOwnerIdConverts OwnerIdBytes to OwnerId.
ownerIdToOwnerIdBytesConverts OwnerId to OwnerIdBytes.
ownerSecretToMnemonicConverts an OwnerSecret to a Mnemonic.
ownerSecretToOwnerIdConverts an OwnerSecret to the OwnerId of the owners it creates, without deriving their keys or mnemonic, such as to tell whether a backup's AppOwner is already on the device.

Variants

NameDescription
AppOwnerThe 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.
ShardOwnerAn Owner for sharding data.
SharedOwnerAn Owner for collaborative data with write access.
SharedReadonlyOwnerRead-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.
createAppOwnerCreates an AppOwner from an OwnerSecret.
createShardOwnerCreates a ShardOwner from an OwnerSecret.
createSharedOwnerCreates a SharedOwner from an OwnerSecret for collaborative write access.
createSharedReadonlyOwnerCreates a SharedReadonlyOwner from a SharedOwner.
deriveShardOwnerDerives a ShardOwner from an AppOwner using the specified path.

Transport

NameDescription
OwnerWebSocketTransportWebSocket transport configuration.
RelayUrlErrorError returned when a WebSocketUrl is not a RelayUrl.
RelayUrlFromStringErrorError returned when RelayUrlFromString cannot parse a string as a RelayUrl.
SyncOwnerAn ReadonlyOwner or Owner with non-empty OwnerTransports so it can be synced.
OwnerTransportTransport configuration for connecting to relays.
RelayUrlWebSocketUrl of a relay, which has no query, such as wss://free.evoluhq.com/.
relayHeartbeatIntervalThe longest a relay waits between heartbeats on an idle connection, as OwnerWebSocketTransport describes: thirty seconds.
RelayUrlWebSocketUrl of a relay, which has no query, such as wss://free.evoluhq.com/.
RelayUrlFromStringTransforms a relay URL into its canonical RelayUrl.
createOwnerWebSocketTransportCreates an OwnerWebSocketTransport for the given RelayUrl and OwnerId, which it adds as the ownerId query parameter.
parseOwnerIdFromOwnerWebSocketTransportUrlExtracts OwnerId from the URL of an OwnerWebSocketTransport or the request target of its handshake.

Testing

VariableDescription
testAppOwnerDeterministic AppOwner for tests. Its secret is public, so anyone can read data stored or synced with it.
testOwnerSecretDeterministic OwnerSecret for tests.