Biometria com LocalAuthentication

npx expo install expo-local-authentication expo-secure-store

{
  "expo": {
    "ios": {
      "infoPlist": {
        "NSFaceIDUsageDescription": "Desbloquear MyApp e confirmar ações sensíveis."
      }
    }
  }
}

import * as LocalAuthentication from "expo-local-authentication";
 
export type BiometricCapability =
  | { available: false; reason: "no_hardware" | "not_enrolled" }
  | { available: true; types: LocalAuthentication.AuthenticationType[] };
 
export async function getBiometricCapability(): Promise<BiometricCapability> {
  const hasHardware = await LocalAuthentication.hasHardwareAsync();
  if (!hasHardware) {
    return { available: false, reason: "no_hardware" };
  }
 
  const enrolled = await LocalAuthentication.isEnrolledAsync();
  if (!enrolled) {
    return { available: false, reason: "not_enrolled" };
  }
 
  const types = await LocalAuthentication.supportedAuthenticationTypesAsync();
  return { available: true, types };
}

import { useEffect, useState } from "react";
import { ActivityIndicator, View } from "react-native";
import * as LocalAuthentication from "expo-local-authentication";
import { secureTokenStorage } from "@/features/auth/adapters/secureTokenStorage";
import { refreshFromStoredToken } from "@/features/auth/api/refreshSession";
 
type UnlockState = "checking" | "locked" | "unlocked";
 
export function BiometricGate({ children }: { children: React.ReactNode }) {
  const [state, setState] = useState<UnlockState>("checking");
 
  useEffect(() => {
    (async () => {
      const token = await secureTokenStorage.loadRefreshToken();
      if (!token) {
        setState("unlocked"); // sem sessão - o fluxo de autenticação cuida do login
        return;
      }
 
      const capability = await getBiometricCapability();
      if (!capability.available) {
        await refreshFromStoredToken();
        setState("unlocked");
        return;
      }
 
      const result = await LocalAuthentication.authenticateAsync({
        promptMessage: "Desbloquear MyApp",
        cancelLabel: "Sair",
        disableDeviceFallback: false,
      });
 
      if (result.success) {
        await refreshFromStoredToken();
        setState("unlocked");
      } else {
        setState("locked");
      }
    })();
  }, []);
 
  if (state === "checking") {
    return (
      <View style={{ flex: 1, justifyContent: "center", alignItems: "center" }}>
        <ActivityIndicator />
      </View>
    );
  }
 
  if (state === "locked") {
    return <SignOutOrRetryScreen onRetry={() => setState("checking")} />;
  }
 
  return <>{children}</>;
}

import * as LocalAuthentication from "expo-local-authentication";
 
export async function requireStepUpAuth(actionLabel: string): Promise<boolean> {
  const capability = await getBiometricCapability();
 
  if (!capability.available) {
    // Retorne para um modal de senha ou desafio MFA
    return promptPasswordModal(actionLabel);
  }
 
  const result = await LocalAuthentication.authenticateAsync({
    promptMessage: `Confirmar ${actionLabel}`,
    fallbackLabel: "Usar código PIN",
  });
 
  return result.success;
}

// Tela de transferência bancária
async function handleTransfer() {
  const confirmed = await requireStepUpAuth("transferência bancária");
  if (!confirmed) return;
 
  await api.post("/transfers", { amount, toAccount });
}

import AsyncStorage from "@react-native-async-storage/async-storage";
 
const BIOMETRIC_PREF_KEY = "prefs.biometric_unlock_enabled";
 
export async function isBiometricUnlockEnabled() {
  return (await AsyncStorage.getItem(BIOMETRIC_PREF_KEY)) === "1";
}
 
export async function setBiometricUnlockEnabled(enabled: boolean) {
  if (enabled) {
    const capability = await getBiometricCapability();
    if (!capability.available) {
      throw new Error("Biometria não disponível neste dispositivo");
    }
    // Prove o registro funciona antes de salvar a preferência
    const result = await LocalAuthentication.authenticateAsync({
      promptMessage: "Habilitar desbloqueio biométrico",
    });
    if (!result.success) return false;
  }
 
  await AsyncStorage.setItem(BIOMETRIC_PREF_KEY, enabled ? "1" : "0");
  return true;
}

┌────────────────┬─────────────────────────────┬──────────────────────────────┐
│ Preocupação    │ iOS                         │ Android                      │
├────────────────┼─────────────────────────────┼──────────────────────────────┤
│ Rosto          │ Face ID (TrueDepth)         │ Desbloqueio facial (dependente do fornecedor)│
│ Impressão Digital │ Touch ID (dispositivos mais antigos) │ Impressão digital / sob a tela │
│ Fallback       │ Código PIN do dispositivo via sistema │ PIN/padrão do dispositivo           │
│ Solicitação    │ Folha no estilo ASAuthorization │ API BiometricPrompt          │
│ Cancelar       │ Cancelamento do usuário ≠ bloqueio por falha │ Específico do fornecedor         │
└────────────────┴─────────────────────────────┴──────────────────────────────┘

import { Platform } from "react-native";
 
const promptMessage = Platform.select({
  ios: "Desbloquear com Face ID",
  android: "Confirmar com impressão digital",
  default: "Autenticar",
});

O que a biometria FAZ                  O que a biometria NÃO FAZ
────────────────────────────────────  ─────────────────────────────────────
Prova presença recente do usuário     Substitui MFA do lado do servidor
Acelera a UX de retorno do usuário    Criptografa dados (use SecureStore)
Reduz "shoulder-surfing" vs digitar PIN Sobrevive à extração de jailbreak sozinha
Atende a algumas UX de escalonamento regulamentadas | Prova de identidade para sua API sem backend