SecureStore & Keychain/Keystore

expo-secure-store es la bóveda de tokens predeterminada para aplicaciones Expo. Delega en iOS Keychain y Android Keystore, manteniendo los tokens de refresco fuera de SQLite sin cifrar (AsyncStorage) y fuera de tu bundle de JS.

Requisitos previos

npx expo install expo-secure-store

No se requiere plugin de configuración para el uso básico en SDK 57 - instala e importa.

Herramientas: Estos ejemplos se dirigen a Expo SDK 57 (expo ~57.0.4), React Native 0.86.0 y React 19.2.3.

Por qué no usar AsyncStorage para secretos

Comparación del modelo de amenaza
 
AsyncStorage          SecureStore (Keychain / Keystore)
────────────────────  ─────────────────────────────────────────
SQLite sin cifrar     Cifrado respaldado por hardware (dependiente del dispositivo)
Legible en            Requiere desbloqueo del dispositivo + permisos de aplicación
  dispositivos rooteados  en iOS; Keystore en Android
  con navegadores de
  archivos
Respaldado como datos WHEN_UNLOCKED_THIS_DEVICE_ONLY excluye
  de aplicación sin      la sincronización de iCloud Keychain (iOS)
  cifrar en algunas
  copias de seguridad
  de Android

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

• AsyncStorage es apropiado para tema, última pestaña y estado de UI en borrador - no credenciales
• Los atacantes con acceso físico al dispositivo y herramientas de jailbreak/root pueden volcar AsyncStorage trivialmente
• Los marcos de cumplimiento (anexos móviles PCI, SOC2) marcan explícitamente el almacenamiento de credenciales locales sin cifrar
• Grep en PRs para AsyncStorage + token - automatiza en CI con una regla ESLint personalizada

Relacionado: ../expo-rules/security-rules-for-mobile/security-rules-for-mobile.md - Reglas de almacenamiento de Tier 2

Adaptador de almacenamiento de tokens

Envuelve SecureStore detrás de una interfaz para que las pruebas cambien en memoria y las migraciones se mantengan centralizadas.

// 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)),
    );
  },
};

• Las claves con espacios de nombres (auth.refresh_token) evitan colisiones con otras características que usan SecureStore
• Exporta un único adaptador - las pantallas nunca llaman a SecureStore directamente
• clearAll es la primitiva de cierre de sesión - llama desde flujos de cierre de sesión y cambio de cuenta
• Mantén las claves en un módulo - los literales de cadena dispersos causan secretos huérfanos después de refactorizaciones

Relacionado: Mobile Auth Basics - restauración de sesión de inicio en frío

Opciones de accesibilidad de Keychain

Los controles de accesibilidad de iOS Keychain controlan cuándo se pueden leer los elementos.

import * as SecureStore from "expo-secure-store";
 
// Recomendado para tokens de refresco:
SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY
 
// Alternativas - usa deliberadamente:
SecureStore.AFTER_FIRST_UNLOCK          // la actualización en segundo plano puede leer - riesgo más alto
SecureStore.WHEN_UNLOCKED                 // puede sincronizarse a través de iCloud Keychain
SecureStore.ALWAYS                        // evita para secretos de autenticación

• Por defecto a WHEN_UNLOCKED_THIS_DEVICE_ONLY para tokens de refresco - se alinea con la postura de aplicaciones bancarias
• Elige AFTER_FIRST_UNLOCK solo cuando debas actualizar en segundo plano antes del primer desbloqueo y aceptes el compromiso
• Android asigna estos a niveles de protección equivalentes de Keystore - Expo abstrae las diferencias de plataforma
• Documenta la elección en un ADR si el cumplimiento pregunta por qué la actualización en segundo plano funciona antes del desbloqueo

Límites de tamaño y qué no almacenar

SecureStore es para pequeños secretos - no cachés JSON arbitrarios.

// ❌ Demasiado grande - objeto de usuario con URL de avatar, preferencias, roles
await SecureStore.setItemAsync("user", JSON.stringify(largeUserObject));
 
// ✅ Almacena token + ID no sensible; obtén perfil de la API
await SecureStore.setItemAsync("auth.refresh_token", refreshToken, secureOptions);
await SecureStore.setItemAsync("auth.last_user_id", userId, secureOptions);

• Expo documenta un límite de ~2048 bytes por valor - los payloads oversized fallan en tiempo de ejecución
• Almacena perfiles de usuario en la caché de TanStack Query o MMKV encriptado si se requieren lecturas sin conexión - no SecureStore
• Almacena tokens de acceso en memoria cuando sea posible - solo persiste tokens de refresco a menos que lo offline requiera de otra manera
• Si necesitas blobs encriptados grandes, evalúa react-native-mmkv con la clave de encriptación almacenada en SecureStore

Migración desde AsyncStorage

Envía una migración única para aplicaciones que previamente almacenaban tokens incorrectamente.

// 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");
}

• Ejecuta la migración antes de la actualización de inicio en frío en el bootstrap de AuthProvider
• Elimina las entradas legadas de AsyncStorage inmediatamente después de escribir correctamente en SecureStore
• Establece un indicador de migración para que la ruta se ejecute una vez - no en cada lanzamiento
• Registra el éxito de la migración en análisis (sin valores de token) para medir la adopción

Lecturas con puerta biométrica (capa opcional)

SecureStore almacena secretos; la biometría controla el acceso a la aplicación - ver la página de biometría dedicada para patrones de step-up.

// SecureStore mantiene el token; la biometría controla si la aplicación desbloquea la sesión
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: "Desbloquea MyApp",
    fallbackLabel: "Usa código de acceso",
  });
 
  if (!result.success) {
    await signOut();
    return null;
  }
 
  return loadRefresh();
}

• La biometría no reemplaza SecureStore - agrega una verificación de presencia del usuario antes de leer tokens
• La biometría fallida después de N intentos no debe eliminar tokens automáticamente - ofrece cerrar sesión explícitamente
• En Android, el desbloqueo por huella dactilar y rostro se asignan a la misma API authenticateAsync

Relacionado: Biometrics with LocalAuthentication - patrones de autenticación step-up

Cierre de sesión y eliminación de claves

export async function signOutCompletely(queryClient: { clear: () => void }) {
  await secureTokenStorage.clearAll();
  queryClient.clear();
  // Reinicio de navegación manejado por el llamador - router.replace("/sign-in")
}

• deleteItemAsync es idempotente - seguro de llamar cuando la clave ya está ausente
• La falta de limpieza de cierre de sesión es un hallazgo principal de auditoría de seguridad móvil - prueba: cerrar sesión - matar aplicación - relanzar - sin llamadas API autenticadas
• Empareja con revocación de servidor cuando el usuario selecciona "Cerrar sesión en todas partes"

Pruebas de SecureStore en Jest

Simula el módulo en Jest - SecureStore no está disponible en Node.

// 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",
}));

• Pruebas unitarias de tu lógica de adaptador con la simulación - no el bridge nativo de Expo
• Las pruebas E2E (Detox) deben ejecutarse en dispositivo/simulador para el comportamiento real de Keychain
• iOS Simulator Keychain persiste en la eliminación de aplicaciones en algunas versiones de Xcode - restablece el contenido del simulador cuando las pruebas se cuelgan

Preguntas frecuentes

Relacionado

• Mobile Auth Basics - roles de tokens y restauración de inicio en frío
• Biometrics with LocalAuthentication - control de acceso a sesiones almacenadas
• Multi-Account & Device Binding - claves de almacenamiento seguro por cuenta
• ../expo-rules/security-rules-for-mobile/security-rules-for-mobile.md - reglas de almacenamiento por tier
• ../expo-sdk/expo-secure-store-and-expo-crypto/expo-secure-store-and-expo-crypto.md - hashing y bytes aleatorios con expo-crypto

Versiones de stack: Esta página se escribió para React 19.2.3, React Native 0.86.0 y Expo SDK 57 (expo ~57.0.4).