API reference › @evolu/react-native › loadDeviceSecret

function loadDeviceSecret(
  appName: string & Brand<"UrlSafeString"> & Brand<"AppName">,
): Task<
  Uint8Array<ArrayBufferLike> &
    Brand<"Entropy"> &
    Brand<"Length32"> &
    Brand<"DeviceSecret">,
  LoadDeviceSecretError
>;

Defined in: react-native/src/DeviceSecret.ts:71

Loads the app's DeviceSecret from the platform's secure storage, and on the first use creates and stores one, without a prompt. Pass it to createEvoluApp as { type: "DeviceSecret", secret }.

On iOS, the Keychain keeps it, readable after the device's first unlock and never moved to another device or iCloud. iOS keeps the Keychain items of a removed app, so it survives a reinstall. It goes to the app's default access group, the first keychain access group the app lists, if any, which other apps of its team may share: they can read it, though their own lookups never match it, and a later build without that group finds none and creates another, which leaves the device database with nothing to open it. Android encrypts it with an Android Keystore key of the app name's own in a file that backups leave out, so a restored backup starts with a new one. It never replaces a stored secret it can't read, which would leave the device database with nothing to open it, except on iOS for a Keychain item the Keychain itself can't decrypt: that item reads as missing, so a new secret replaces it, and the device database it opened can't be opened again.

A new device, also one restored from a backup, gets a new DeviceSecret, which opens a new device database, so the AppOwners of the old device come back only from their backups, such as their mnemonics.

It fails with DeviceSecretStorageUnavailableError while the storage can't be read yet, with DeviceSecretUnreadableError when it holds a secret it can't read, which happens only on Android, and with an UnknownError otherwise. A Keystore key broken in a way Android doesn't report, which before Android 13 is any broken key, fails with an UnknownError; when that lasts after a restart of the device, an app may offer forgetDeviceSecret too.