SecureStore & Keychain/Keystore

npx expo install expo-secure-store

Threat model comparison
 
AsyncStorage          SecureStore (Keychain / Keystore)
────────────────────  ─────────────────────────────────────────
Unencrypted SQLite    Hardware-backed encryption (device-dependent)
Readable on rooted    Requires device unlock + app entitlement
  devices with file     on iOS; Keystore-backed on Android
  browsers
Backed up as plain    WHEN_UNLOCKED_THIS_DEVICE_ONLY excludes
  app data in some      iCloud Keychain sync (iOS)
  Android backups

// ❌ Never do this
import AsyncStorage from "@react-native-async-storage/async-storage";
await AsyncStorage.setItem("refresh_token", token);
 
// ✅ Correct
import * as SecureStore from "expo-secure-store";
await SecureStore.setItemAsync("auth.refresh_token", token, {
  keychainAccessible: SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
});

// src/features/auth/adapters/secureTokenStorage.ts
import * as SecureStore from "expo-secure-store";
 
const KEYS = {
  refreshToken: "auth.refresh_token",
  lastUserId: "auth.last_user_id",
} as const;
 
const secureOptions: SecureStore.SecureStoreOptions = {
  keychainAccessible: SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
};
 
export const secureTokenStorage = {
  async saveRefreshToken(token: string) {
    await SecureStore.setItemAsync(KEYS.refreshToken, token, secureOptions);
  },
 
  async loadRefreshToken() {
    return SecureStore.getItemAsync(KEYS.refreshToken, secureOptions);
  },
 
  async clearAll() {
    await Promise.all(
      Object.values(KEYS).map((key) => SecureStore.deleteItemAsync(key)),
    );
  },
};

import * as SecureStore from "expo-secure-store";
 
// Recommended for refresh tokens:
SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY
 
// Alternatives - use deliberately:
SecureStore.AFTER_FIRST_UNLOCK          // background fetch can read - higher risk
SecureStore.WHEN_UNLOCKED                 // may sync via iCloud Keychain
SecureStore.ALWAYS                        // avoid for auth secrets

// ❌ Too large - user object with avatar URL, preferences, roles
await SecureStore.setItemAsync("user", JSON.stringify(largeUserObject));
 
// ✅ Store token + non-sensitive ID; fetch profile from API
await SecureStore.setItemAsync("auth.refresh_token", refreshToken, secureOptions);
await SecureStore.setItemAsync("auth.last_user_id", userId, secureOptions);

// src/features/auth/adapters/migrateTokenStorage.ts
import AsyncStorage from "@react-native-async-storage/async-storage";
import * as SecureStore from "expo-secure-store";
 
const LEGACY_KEY = "refresh_token";
const SECURE_KEY = "auth.refresh_token";
const MIGRATION_FLAG = "auth.storage_migrated_v1";
 
export async function migrateLegacyTokens() {
  const done = await AsyncStorage.getItem(MIGRATION_FLAG);
  if (done) return;
 
  const legacy = await AsyncStorage.getItem(LEGACY_KEY);
  if (legacy) {
    await SecureStore.setItemAsync(SECURE_KEY, legacy, {
      keychainAccessible: SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
    });
    await AsyncStorage.removeItem(LEGACY_KEY);
  }
 
  await AsyncStorage.setItem(MIGRATION_FLAG, "1");
}

// SecureStore holds the token; biometrics gate whether app unlocks session
import * as LocalAuthentication from "expo-local-authentication";
 
export async function unlockAppOrSignOut(
  loadRefresh: () => Promise<string | null>,
  signOut: () => Promise<void>,
) {
  const hasHardware = await LocalAuthentication.hasHardwareAsync();
  const enrolled = await LocalAuthentication.isEnrolledAsync();
 
  if (!hasHardware || !enrolled) {
    return loadRefresh();
  }
 
  const result = await LocalAuthentication.authenticateAsync({
    promptMessage: "Unlock MyApp",
    fallbackLabel: "Use passcode",
  });
 
  if (!result.success) {
    await signOut();
    return null;
  }
 
  return loadRefresh();
}

export async function signOutCompletely(queryClient: { clear: () => void }) {
  await secureTokenStorage.clearAll();
  queryClient.clear();
  // Navigation reset handled by caller - router.replace("/sign-in")
}

// jest.setup.ts
jest.mock("expo-secure-store", () => ({
  setItemAsync: jest.fn(),
  getItemAsync: jest.fn(),
  deleteItemAsync: jest.fn(),
  WHEN_UNLOCKED_THIS_DEVICE_ONLY: "WHEN_UNLOCKED_THIS_DEVICE_ONLY",
}));