expo-secure-store & expo-crypto

Segredos, hashing e bytes aleatórios no dispositivo - o cookbook do expo-secure-store e expo-crypto para aplicativos Expo SDK 57 que armazenam tokens de atualização, derivam impressões digitais e geram nonces.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

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

Quando usar:

• Tokens de atualização e chaves de API que devem sobreviver a reinicializações do aplicativo.
• Geração de code_verifier PKCE para OAuth - veja auth-session.
• Chaves de cache endereçadas por conteúdo (hash de URL + etag).
• Impressões digitais de vinculação de dispositivo (hash de ID de dispositivo estável + salt do servidor).

Quando evitar:

• Grandes blocos JSON - limite de tamanho do item do SecureStore (~2048 bytes).
• Senhas que você pode validar localmente - clientes móveis não são confiáveis; use autenticação de servidor.
• Substituição de TLS - os utilitários de criptografia complementam a segurança do transporte, não substituem o HTTPS.

Exemplo de Trabalho

Adaptador de cofre de tokens, purga de logout e chaves de cache com hash e IDs aleatórios 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);
  // Também: queryClient.clear(), router.replace('/sign-in') - veja auth-session
}

O que isso demonstra:

• Namespaces de chaves por usuário - múltiplas contas sem vazamento de token.
• WHEN_UNLOCKED_THIS_DEVICE_ONLY - exclui a sincronização do iCloud Keychain.
• Chaves de cache SHA-256 - nomes de arquivo estáveis sem PII de URL bruto em caminhos.
• Logout limpa o cofre - emparelhado com navegação e cache da Query em auth-session.

Mergulho Profundo

Limites e Opções do SecureStore

await SecureStore.setItemAsync("pin.step_up", "verified", {
  requireAuthentication: true, // iOS: Face ID para ler
  authenticationPrompt: "Confirme a identidade para ver a conta",
});

• requireAuthentication é um portão biométrico apenas para iOS - combine com ../auth-session/biometrics-with-localauthentication/biometrics-with-localauthentication.md.
• O suporte do Android Keystore depende do dispositivo - ainda muito melhor que AsyncStorage.

Capacidades do expo-crypto

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

• Use getRandomBytes para verifiers PKCE - nunca Math.random().
• Hashing é unidirecional - não é possível recuperar a entrada; adequado para impressões digitais, não para criptografia.

Lembrete de Camada de Armazenamento

Token de atualização     → expo-secure-store
Token de acesso      → memória ou sessão SecureStore curta
Preferências do usuário  → AsyncStorage / MMKV
Fotos            → caminhos do expo-file-system

• Leia também ../auth-session/securestore-and-keychain-keystore/securestore-and-keychain-keystore.md para ADRs completos de armazenamento de autenticação.
• Leia também ../auth-session/mobile-auth-basics/mobile-auth-basics.md para modelos de sessão.

Logout e Troca de Conta

// Sequência mínima de logout
await SecureStore.deleteItemAsync("auth.refresh_token");
queryClient.clear();
router.replace("/sign-in");

• Troca de conta: limpe chaves por usuário antes de carregar o token de atualização do próximo usuário.
• Nomeie as chaves com userId - auth.refresh_token.${userId}.

Armadilhas

• AsyncStorage para tokens de atualização - Despejo trivial em dispositivos com root. Correção: Apenas SecureStore.
• Armazenar o perfil de usuário inteiro no SecureStore - Excede o limite de tamanho. Correção: Busca na API + SQLite/Cache da Query.
• Math.random para verifier OAuth - Previsível. Correção: Crypto.getRandomBytes.
• Esquecer SecureStore no logout - O próximo usuário herda a sessão. Correção: Lista explícita de deleteItemAsync.
• Registrar digests de segredos - Ainda auxilia tentativas de cracking offline. Correção: nunca registre material de token.
• Assumir que SecureStore criptografa de JS - A proteção é o keystore do sistema operacional - ainda envie tokens apenas via HTTPS.

Alternativas

FAQs

npx expo install expo-secure-store expo-crypto

Relacionados

• Noções Básicas do Expo SDK - instalação de módulo
• expo-file-system - arquivos não são um cofre
• ../auth-session/securestore-and-keychain-keystore/securestore-and-keychain-keystore.md - padrões de Keychain
• ../auth-session/mobile-auth-basics/mobile-auth-basics.md - modelos de sessão
• ../expo-rules/security-rules-for-mobile/security-rules-for-mobile.md - regras de armazenamento
• Melhores Práticas de Pacotes do Expo SDK - checklist de segredos

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).