SecureStore & Keychain/Keystore

expo-secure-store é o cofre de tokens padrão para aplicativos Expo. Ele delega para iOS Keychain e Android Keystore, mantendo os tokens de atualização fora do SQLite não criptografado (AsyncStorage) e fora do seu bundle JS.

Pré-requisitos

npx expo install expo-secure-store

Nenhum plugin de configuração é necessário para uso básico no SDK 57 - instale e importe.

Ferramentas: Estes exemplos visam Expo SDK 57 (expo ~57.0.4), React Native 0.86.0 e React 19.2.3.

Por que não AsyncStorage para Segredos

Comparação do modelo de ameaça
 
AsyncStorage          SecureStore (Keychain / Keystore)
────────────────────  ─────────────────────────────────────────
SQLite não criptografado    Criptografia com suporte de hardware (dependente do dispositivo)
Legível em dispositivos     Requer desbloqueio do dispositivo + permissão do app
  com root e navegadores      no iOS; com suporte do Keystore no Android
  de arquivos
Faz backup como dados       WHEN_UNLOCKED_THIS_DEVICE_ONLY exclui
  simples do app em alguns    a sincronização do iCloud Keychain (iOS)
  backups Android

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

• AsyncStorage é apropriado para tema, última aba e estado de UI em rascunho - não credenciais
• Atacantes com acesso físico ao dispositivo e ferramentas de jailbreak/root podem extrair AsyncStorage trivialmente
• Frameworks de conformidade (PCI, anexos móveis SOC2) sinalizam explicitamente o armazenamento local não criptografado de credenciais
• Use grep em PRs para AsyncStorage + token - automatize em CI com uma regra ESLint personalizada

Relacionado: ../expo-rules/security-rules-for-mobile/security-rules-for-mobile.md - Regras de armazenamento de Nível 2

Adaptador de Armazenamento de Tokens

Encapsule o SecureStore atrás de uma interface para que os testes troquem por memória e as migrações permaneçam 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)),
    );
  },
};

• Chaves com namespace (auth.refresh_token) evitam colisões com outros recursos que usam SecureStore
• Exporte um adaptador único - as telas nunca chamam SecureStore diretamente
• clearAll é a primitiva de logout - chame em fluxos de saída e troca de conta
• Mantenha as chaves em um módulo - literais de string espalhados causam segredos órfãos após refatorações

Relacionado: Noções Básicas de Autenticação Móvel - restauração de sessão de inicialização a frio

Opções de Acessibilidade do Keychain

A acessibilidade do iOS Keychain controla quando os itens podem ser lidos.

import * as SecureStore from "expo-secure-store";
 
// Recomendado para tokens de atualização:
SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY
 
// Alternativas - use deliberadamente:
SecureStore.AFTER_FIRST_UNLOCK          // leitura em segundo plano possível - risco maior
SecureStore.WHEN_UNLOCKED                 // pode sincronizar via iCloud Keychain
SecureStore.ALWAYS                        // evite para segredos de autenticação

• Padrão para WHEN_UNLOCKED_THIS_DEVICE_ONLY para tokens de atualização - corresponde à postura de aplicativos bancários
• Escolha AFTER_FIRST_UNLOCK apenas quando precisar atualizar em segundo plano antes do primeiro desbloqueio e aceitar a troca
• O Android mapeia isso para níveis de proteção equivalentes do Keystore - o Expo abstrai as diferenças de plataforma
• Documente a escolha em um ADR se a conformidade perguntar por que a atualização em segundo plano funciona antes do desbloqueio

Limites de Tamanho e O Que Não Armazenar

SecureStore é para segredos pequenos - não caches JSON arbitrários.

// ❌ Muito grande - objeto de usuário com URL de avatar, preferências, funções
await SecureStore.setItemAsync("user", JSON.stringify(largeUserObject));
 
// ✅ Armazene o token + ID não sensível; busque o perfil da API
await SecureStore.setItemAsync("auth.refresh_token", refreshToken, secureOptions);
await SecureStore.setItemAsync("auth.last_user_id", userId, secureOptions);

• O Expo documenta um limite de ~2048 bytes por valor - payloads excessivamente grandes falham em tempo de execução
• Armazene perfis de usuário no cache TanStack Query ou MMKV criptografado se leituras offline forem necessárias - não no SecureStore
• Armazene tokens de acesso em memória quando possível - persista apenas tokens de atualização, a menos que a demanda offline exija o contrário
• Se você precisar de blobs criptografados grandes, avalie react-native-mmkv com a chave de criptografia armazenada no SecureStore

Migração do AsyncStorage

Envie uma migração única para aplicativos que anteriormente armazenavam tokens incorretamente.

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

• Execute a migração antes da atualização a frio na inicialização do AuthProvider
• Exclua entradas legadas do AsyncStorage imediatamente após a gravação bem-sucedida no SecureStore
• Defina um flag de migração para que o caminho seja executado uma vez - não a cada inicialização
• Registre o sucesso da migração em análises (sem valores de token) para medir a adoção

Leituras com Biometria (Camada Opcional)

SecureStore armazena segredos; a biometria controla o acesso ao aplicativo - veja a página dedicada de biometria para padrões de escalonamento.

// SecureStore contém o token; a biometria controla se o aplicativo desbloqueia a sessão
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();
}

• A biometria não substitui o SecureStore - ela adiciona uma verificação de presença do usuário antes de ler os tokens
• Falhas biométricas após N tentativas não devem excluir tokens automaticamente - ofereça logout explicitamente
• No Android, o desbloqueio por impressão digital e facial mapeiam para a mesma API authenticateAsync

Relacionado: Biometria com LocalAuthentication - padrões de escalonamento de autenticação

Logout e Exclusão de Chave

export async function signOutCompletely(queryClient: { clear: () => void }) {
  await secureTokenStorage.clearAll();
  queryClient.clear();
  // Redefinição de navegação tratada pelo chamador - router.replace("/sign-in")
}

• deleteItemAsync é idempotente - seguro para chamar quando a chave já está ausente
• A falta de limpeza de logout é uma das principais descobertas de auditoria de segurança móvel - teste: logout → fechar app → reiniciar → nenhuma chamada de API autenticada
• Combine com revogação do servidor quando o usuário selecionar "Sair de todos os dispositivos"

Testando SecureStore no Jest

Simule o módulo no Jest - SecureStore não está disponível no 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",
}));

• Teste unitariamente a lógica do seu adaptador com a simulação - não a ponte nativa do Expo
• Testes E2E (Detox) devem ser executados no dispositivo/simulador para o comportamento real do Keychain
• O Keychain do simulador iOS persiste entre exclusões de aplicativos em algumas versões do Xcode - reinicie o conteúdo do simulador quando os testes falharem

FAQs

Relacionados

• Noções Básicas de Autenticação Móvel - papéis de token e restauração de inicialização a frio
• Biometria com LocalAuthentication - controle de acesso a sessões armazenadas
• Multi-Conta e Vinculação de Dispositivo - chaves de armazenamento seguro por conta
• ../expo-rules/security-rules-for-mobile/security-rules-for-mobile.md - regras de nível de armazenamento
• ../expo-sdk/expo-secure-store-and-expo-crypto/expo-secure-store-and-expo-crypto.md - hashing e bytes aleatórios com expo-crypto

Versões da Stack: Esta página foi escrita para React 19.2.3, React Native 0.86.0 e Expo SDK 57 (expo ~57.0.4).