Biometrics with LocalAuthentication

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

{
  "expo": {
    "ios": {
      "infoPlist": {
        "NSFaceIDUsageDescription": "Unlock MyApp and confirm sensitive actions."
      }
    }
  }
}

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"); // no session - auth flow handles sign-in
        return;
      }
 
      const capability = await getBiometricCapability();
      if (!capability.available) {
        await refreshFromStoredToken();
        setState("unlocked");
        return;
      }
 
      const result = await LocalAuthentication.authenticateAsync({
        promptMessage: "Unlock MyApp",
        cancelLabel: "Sign out",
        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) {
    // Fall back to password modal or MFA challenge
    return promptPasswordModal(actionLabel);
  }
 
  const result = await LocalAuthentication.authenticateAsync({
    promptMessage: `Confirm ${actionLabel}`,
    fallbackLabel: "Use passcode",
  });
 
  return result.success;
}

// Wire transfer screen
async function handleTransfer() {
  const confirmed = await requireStepUpAuth("wire transfer");
  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("Biometrics not available on this device");
    }
    // Prove enrollment works before saving preference
    const result = await LocalAuthentication.authenticateAsync({
      promptMessage: "Enable biometric unlock",
    });
    if (!result.success) return false;
  }
 
  await AsyncStorage.setItem(BIOMETRIC_PREF_KEY, enabled ? "1" : "0");
  return true;
}

┌────────────────┬─────────────────────────────┬──────────────────────────────┐
│ Concern        │ iOS                         │ Android                      │
├────────────────┼─────────────────────────────┼──────────────────────────────┤
│ Face           │ Face ID (TrueDepth)         │ Face unlock (vendor-dependent)│
│ Fingerprint    │ Touch ID (older devices)    │ Fingerprint / under-display  │
│ Fallback       │ Device passcode via system  │ Device PIN/pattern           │
│ Prompt         │ ASAuthorization-style sheet │ BiometricPrompt API          │
│ Cancel         │ User cancel ≠ failure lock  │ Vendor-specific              │
└────────────────┴─────────────────────────────┴──────────────────────────────┘

import { Platform } from "react-native";
 
const promptMessage = Platform.select({
  ios: "Unlock with Face ID",
  android: "Confirm with fingerprint",
  default: "Authenticate",
});

What biometrics DO                    What biometrics DO NOT
────────────────────────────────────  ─────────────────────────────────────
Prove recent user presence            Replace server-side MFA
Speed up returning-user UX            Encrypt data (use SecureStore)
Reduce shoulder-surfing vs typing PIN   Survive jailbreak extraction alone
Meet some regulatory step-up UX       Prove identity to your API without backend