MMKV and AsyncStorage keep data in the app's sandbox in plain form. Tokens, refresh tokens and
encryption keys belong in the Keychain (iOS) or the Android Keystore, which expo-secure-store
uses. This guide puts a token there and uses a generated key to encrypt MMKV.
npx expo install expo-secure-store
import * as SecureStore from 'expo-secure-store';
import { createStorage, secureStoreDriver } from 'react-native-storage-toolkit';
import { z } from 'zod';
const secure = createStorage({
driver: secureStoreDriver(SecureStore, {
keychainAccessible: SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
}),
namespace: 'auth',
});
export const refreshToken = secure.item('refresh-token', { schema: z.string().min(1) });
await refreshToken.set(tokenFromServer);
const token = await refreshToken.get(); // string | undefined
await refreshToken.remove(); // on sign-out
Things to know about this driver:
WHEN_UNLOCKED_THIS_DEVICE_ONLY keeps
the value out of backups and off other devices.keys() and clear() reject with UNSUPPORTED. Remove
each item on sign-out.SECURE_STORE_MAX_VALUE_BYTES); the SecureStore
documentation notes that some iOS releases refused larger ones. Store a token, not a profile.useStorageItem starts with status: 'loading'.auth:refresh-token becomes
auth_3a_refresh-token.MMKV can encrypt its file. The key has to live somewhere safer than the file itself.
getOrCreateSecret returns the key stored in a SecureStore item or creates a random one the first
time. Concurrent calls for one key share the first call, also through two items declared for
that key, so two screens starting at once cannot create two different keys.
A new key is written only when nothing is stored. getOrCreateSecret never overwrites a stored
value it cannot use, because everything encrypted with the old key would become unreadable:
CORRUPT_DATA,
VALIDATION_FAILED or INCOMPATIBLE_VERSION);CORRUPT_DATA;EXPIRED, so give the item no ttl;DRIVER_ERROR.The stored text stays as it is in every case. Deciding what happens next is left to the app:
call mmkvKey.remove() and open the storage again only when the encrypted data may be lost.
npx expo install expo-crypto
import * as Crypto from 'expo-crypto';
import { createMMKV } from 'react-native-mmkv';
import { createStorage, getOrCreateSecret, mmkvDriver } from 'react-native-storage-toolkit';
const mmkvKey = secure.item('mmkv-key', { schema: z.string() });
export async function openEncryptedStorage() {
const encryptionKey = await getOrCreateSecret(mmkvKey, {
length: 16,
getRandomValues: Crypto.getRandomValues,
});
const mmkv = createMMKV({ id: 'private', encryptionKey });
return createStorage({ driver: mmkvDriver(mmkv), namespace: 'private' });
}
length: 16 matches MMKV's default AES-128 key size; use 32 with encryptionType: 'AES-256'.
The secret uses the characters A–Z, a–z and 0–9 with equal probability (bytes that would favour
some characters are dropped), so 16 characters carry about 95 bits.
Without getRandomValues, the function uses globalThis.crypto.getRandomValues and explains what
to install when the runtime has none.
StorageError messages name the key and the reason, never the value or its property names, so
they are safe to send to crash reporting. Where in the value a problem is, and a schema's own
messages, which can quote the value, are kept apart in error.issues. The cause of a DRIVER_ERROR is the native module's error, unchanged.