expo-secure-store & expo-crypto

Secretos, hashing y bytes aleatorios en el dispositivo - el manual de expo-secure-store y expo-crypto para aplicaciones Expo SDK 57 que guardan tokens de actualización, generan huellas digitales y producen nonces.

Receta

Tarjeta de referencia rápida - lista para copiar y pegar.

npx expo install expo-secure-store expo-crypto

import * as SecureStore from "expo-secure-store";
 
const REFRESH_KEY = "auth.refresh_token";
 
export async function saveRefreshToken(token: string) {
  await SecureStore.setItemAsync(REFRESH_KEY, token, {
    keychainAccessible: SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
  });
}
 
export async function loadRefreshToken(): Promise<string | null> {
  return SecureStore.getItemAsync(REFRESH_KEY);
}
 
export async function clearAuthSecrets() {
  await SecureStore.deleteItemAsync(REFRESH_KEY);
}

import * as Crypto from "expo-crypto";
 
export async function sha256Hex(input: string) {
  return Crypto.digestStringAsync(
    Crypto.CryptoDigestAlgorithm.SHA256,
    input
  );
}
 
export function randomNonce(bytes = 16) {
  return Crypto.getRandomBytes(bytes);
}

Cuándo usarlo:

• Tokens de actualización y claves de API que deben persistir entre reinicios de aplicación.
• Generación de code_verifier PKCE para OAuth - ver auth-session.
• Claves de caché direccionadas por contenido (hash de URL - etag).
• Huellas digitales de vinculación de dispositivo (hash de ID de dispositivo estable - salt del servidor).

Cuándo evitarlo:

• Blobs JSON grandes - límite de tamaño de elemento de SecureStore (~2048 bytes).
• Contraseñas que puedas validar localmente - los clientes móviles no son confiables; usa autenticación de servidor.
• Reemplazar TLS - los ayudantes de crypto complementan la seguridad de transporte, no reemplazan HTTPS.

Ejemplo de funcionamiento

Adaptador de bóveda de tokens, purga de cierre de sesión y claves de caché con hash con IDs aleatorios seguros.

npx expo install expo-secure-store expo-crypto

// src/auth/secureTokenVault.ts
import * as SecureStore from "expo-secure-store";
 
const keys = {
  refresh: (userId: string) => `auth.refresh_token.${userId}`,
  device: "auth.device_binding",
} as const;
 
export const tokenVault = {
  async saveRefresh(userId: string, token: string) {
    await SecureStore.setItemAsync(keys.refresh(userId), token, {
      keychainAccessible: SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
    });
  },
 
  async loadRefresh(userId: string) {
    return SecureStore.getItemAsync(keys.refresh(userId));
  },
 
  async clearUser(userId: string) {
    await SecureStore.deleteItemAsync(keys.refresh(userId));
  },
 
  async clearAllKnownUsers(userIds: string[]) {
    await Promise.all(userIds.map((id) => tokenVault.clearUser(id)));
    await SecureStore.deleteItemAsync(keys.device);
  },
};

// src/cache/cacheKey.ts
import * as Crypto from "expo-crypto";
 
export async function cacheKeyForUrl(url: string) {
  const hash = await Crypto.digestStringAsync(
    Crypto.CryptoDigestAlgorithm.SHA256,
    url
  );
  return `cache:${hash.slice(0, 16)}`;
}

// src/auth/logout.ts
import { tokenVault } from "./secureTokenVault";
 
export async function logout(userId: string, allUserIds: string[]) {
  await tokenVault.clearAllKnownUsers(allUserIds);
  // También: queryClient.clear(), router.replace('/sign-in') - ver auth-session
}

Lo que demuestra esto:

• Espacios de nombres de clave por usuario - multi-cuenta sin fugas de tokens.
• WHEN_UNLOCKED_THIS_DEVICE_ONLY - excluye la sincronización de iCloud Keychain.
• Claves de caché SHA-256 - nombres de archivo estables sin PII de URL sin procesar en rutas.
• El cierre de sesión limpia la bóveda - emparejado con navegación y caché de Query en auth-session.

Profundización

Límites y opciones de SecureStore

await SecureStore.setItemAsync("pin.step_up", "verified", {
  requireAuthentication: true, // iOS: Face ID para leer
  authenticationPrompt: "Confirma tu identidad para ver la cuenta",
});

• requireAuthentication es una puerta biométrica solo para iOS - empareja con ../auth-session/biometrics-with-localauthentication/biometrics-with-localauthentication.md.
• El almacenamiento de Android Keystore depende del dispositivo - aún mucho mejor que AsyncStorage.

Capacidades de expo-crypto

import * as Crypto from "expo-crypto";
 
const verifier = Crypto.getRandomBytes(32);
const uuid = Crypto.randomUUID();

• Usa getRandomBytes para verificadores PKCE - nunca Math.random().
• El hashing es unidireccional - no se puede recuperar la entrada; adecuado para huellas digitales, no para cifrado.

Recordatorio de nivel de almacenamiento

Token de actualización     → expo-secure-store
Token de acceso      → memoria o sesión breve de SecureStore
Preferencias del usuario  → AsyncStorage / MMKV
Fotos            → rutas de expo-file-system

• Lee también ../auth-session/securestore-and-keychain-keystore/securestore-and-keychain-keystore.md para los ADRs completos de almacenamiento de autenticación.
• Lee también ../auth-session/mobile-auth-basics/mobile-auth-basics.md para modelos de sesión.

Cierre de sesión y cambio de cuenta

// Secuencia mínima de cierre de sesión
await SecureStore.deleteItemAsync("auth.refresh_token");
queryClient.clear();
router.replace("/sign-in");

• Cambio de cuenta: purga las claves por usuario antes de cargar el token de actualización del siguiente usuario.
• Espacios de nombres de claves con userId - auth.refresh_token.${userId}.

Errores comunes

• AsyncStorage para tokens de actualización - Volcado trivial en dispositivos rooteados. Solución: Solo SecureStore.
• Almacenar todo el perfil del usuario en SecureStore - Excede el límite de tamaño. Solución: Fetch de API - caché de SQLite/Query.
• Math.random para el verificador OAuth - Predecible. Solución: Crypto.getRandomBytes.
• Olvidar SecureStore al cerrar sesión - El siguiente usuario hereda la sesión. Solución: lista explícita de deleteItemAsync.
• Registrar resúmenes de secretos - Aún ayuda a intentos de descifrado sin conexión. Solución: nunca registres material de tokens.
• Asumir que SecureStore cifra desde JS - La protección es el almacén de claves del SO - aún envía tokens solo a través de HTTPS.

Alternativas

Preguntas frecuentes

npx expo install expo-secure-store expo-crypto

Relacionado

• Conceptos básicos de Expo SDK - instalación de módulo
• expo-file-system - los archivos no son una bóveda
• ../auth-session/securestore-and-keychain-keystore/securestore-and-keychain-keystore.md - Patrones de Keychain
• ../auth-session/mobile-auth-basics/mobile-auth-basics.md - modelos de sesión
• ../expo-rules/security-rules-for-mobile/security-rules-for-mobile.md - reglas de almacenamiento
• Mejores prácticas de paquetes Expo SDK - lista de verificación de secretos

Versiones de pila: Esta página fue escrita para React 19.2.3, React Native 0.86.0 y Expo SDK 57 (expo ~57.0.4).