feat(biometric-trust): add enrollment-bound trust store and Option C …

…plumbing

Introduce app/lib/biometricTrustStore: a keychain-backed sentinel bound to
ACCESS_CONTROL.BIOMETRY_CURRENT_SET so the OS invalidates it when the device's
enrolment set changes (iOS errSecItemNotFound, Android
KeyPermanentlyInvalidatedException). The store exposes enrol/disenrol/verify/
probeExists and classifies platform errors into a TrustResult union.

Wire the store into handleLocalAuthentication via the Option C pattern: the
upstream verify() runs before the modal opens and its outcome decides whether
to unlock (success), open the passcode modal with biometry available but
auto-prompt suppressed (canceled/error), or fall back to passcode-only
(unavailable / enrollmentChanged — slice 02 will add the disenrol + flag-clear
side effects). PasscodeEnter and ScreenLockedView take a new skipAutoBiometry
prop carried over LOCAL_AUTHENTICATE_EMITTER so the biometry button stays
visible without re-firing the prompt the user just dismissed.

Screen-lock toggle now enrols/disenrols the sentinel alongside flipping
BIOMETRY_ENABLED_KEY so the keychain item and the flag stay in lockstep.

Part of VLN-216.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

app/containers/Passcode/PasscodeEnter.tsx

@@ -15,10 +15,11 @@ import I18n from '../../i18n';
 
 interface IPasscodePasscodeEnter {
 	hasBiometry: boolean;
+	skipAutoBiometry?: boolean;
 	finishProcess: Function;
 }
 
-const PasscodeEnter = ({ hasBiometry, finishProcess }: IPasscodePasscodeEnter) => {
+const PasscodeEnter = ({ hasBiometry, skipAutoBiometry = false, finishProcess }: IPasscodePasscodeEnter) => {
 	const ref = useRef<IBase>(null);
 	let attempts = 0;
 	let lockedUntil: any = false;
@@ -30,7 +31,7 @@ const PasscodeEnter = ({ hasBiometry, finishProcess }: IPasscodePasscodeEnter) =
 	const biometry = async () => {
 		if (hasBiometry && status === TYPE.ENTER) {
 			const result = await biometryAuth();
-			if (result?.success) {
+			if (result.kind === 'success') {
 				finishProcess();
 			}
 		}
@@ -49,7 +50,9 @@ const PasscodeEnter = ({ hasBiometry, finishProcess }: IPasscodePasscodeEnter) =
 		} else {
 			setStatus(TYPE.ENTER);
 		}
-		biometry();
+		if (!skipAutoBiometry) {
+			biometry();
+		}
 	};
 
 	useEffect(() => {

app/lib/biometricTrustStore/index.test.ts

@@ -0,0 +1,152 @@
+import * as Keychain from 'react-native-keychain';
+
+import { biometricTrustStore, classifyError } from './index';
+
+const mockedKeychain = Keychain as jest.Mocked<typeof Keychain>;
+
+const promptCopy = { title: 'Authenticate', cancel: 'Cancel' };
+
+describe('biometricTrustStore', () => {
+	beforeEach(() => {
+		jest.clearAllMocks();
+	});
+
+	describe('classifyError', () => {
+		it('maps Android KeyPermanentlyInvalidatedException to enrollmentChanged', () => {
+			expect(classifyError({ message: 'android.security.keystore.KeyPermanentlyInvalidatedException: ...' })).toEqual({
+				kind: 'enrollmentChanged'
+			});
+		});
+
+		it('maps iOS errSecItemNotFound (-25300) to enrollmentChanged', () => {
+			expect(classifyError({ code: '-25300', message: 'errSecItemNotFound' })).toEqual({ kind: 'enrollmentChanged' });
+		});
+
+		it('maps errSecUserCancel to canceled', () => {
+			expect(classifyError({ message: 'errSecUserCancel' })).toEqual({ kind: 'canceled' });
+		});
+
+		it('maps Android user cancellation to canceled', () => {
+			expect(classifyError({ message: 'AuthenticationCanceled' })).toEqual({ kind: 'canceled' });
+		});
+
+		it('falls back to error with original cause for unknown failures', () => {
+			const cause = new Error('boom');
+			expect(classifyError(cause)).toEqual({ kind: 'error', cause });
+		});
+	});
+
+	describe('enrol', () => {
+		it('writes sentinel with BIOMETRY_CURRENT_SET and WHEN_UNLOCKED_THIS_DEVICE_ONLY', async () => {
+			mockedKeychain.setGenericPassword.mockResolvedValueOnce(true as any);
+
+			const result = await biometricTrustStore.enrol();
+
+			expect(result).toEqual({ kind: 'success' });
+			expect(mockedKeychain.setGenericPassword).toHaveBeenCalledTimes(1);
+			const [, , options] = mockedKeychain.setGenericPassword.mock.calls[0];
+			expect(options).toMatchObject({
+				accessControl: Keychain.ACCESS_CONTROL.BIOMETRY_CURRENT_SET,
+				accessible: Keychain.ACCESSIBLE.WHEN_UNLOCKED_THIS_DEVICE_ONLY
+			});
+		});
+
+		it('classifies setGenericPassword failures', async () => {
+			mockedKeychain.setGenericPassword.mockRejectedValueOnce(new Error('errSecUserCancel'));
+			expect(await biometricTrustStore.enrol()).toEqual({ kind: 'canceled' });
+		});
+	});
+
+	describe('disenrol', () => {
+		it('deletes the sentinel via resetGenericPassword', async () => {
+			mockedKeychain.resetGenericPassword.mockResolvedValueOnce(true as any);
+
+			await biometricTrustStore.disenrol();
+
+			expect(mockedKeychain.resetGenericPassword).toHaveBeenCalledTimes(1);
+		});
+
+		it('swallows errors so a missing sentinel is not fatal', async () => {
+			mockedKeychain.resetGenericPassword.mockRejectedValueOnce(new Error('not found'));
+			await expect(biometricTrustStore.disenrol()).resolves.toBeUndefined();
+		});
+	});
+
+	describe('probeExists', () => {
+		it('uses hasGenericPassword and does not prompt', async () => {
+			mockedKeychain.hasGenericPassword.mockResolvedValueOnce(true);
+
+			const exists = await biometricTrustStore.probeExists();
+
+			expect(exists).toBe(true);
+			expect(mockedKeychain.hasGenericPassword).toHaveBeenCalledTimes(1);
+			expect(mockedKeychain.getGenericPassword).not.toHaveBeenCalled();
+		});
+
+		it('returns false when probe throws', async () => {
+			mockedKeychain.hasGenericPassword.mockRejectedValueOnce(new Error('broken'));
+			expect(await biometricTrustStore.probeExists()).toBe(false);
+		});
+	});
+
+	describe('verify', () => {
+		it('returns unavailable when sentinel does not exist (no prompt)', async () => {
+			mockedKeychain.hasGenericPassword.mockResolvedValueOnce(false);
+
+			const result = await biometricTrustStore.verify({ promptCopy });
+
+			expect(result).toEqual({ kind: 'unavailable' });
+			expect(mockedKeychain.getGenericPassword).not.toHaveBeenCalled();
+		});
+
+		it('returns success when sentinel matches', async () => {
+			mockedKeychain.hasGenericPassword.mockResolvedValueOnce(true);
+			mockedKeychain.getGenericPassword.mockResolvedValueOnce({
+				service: 'svc',
+				username: 'biometric-trust',
+				password: 'v1',
+				storage: 'keychain'
+			} as any);
+
+			const result = await biometricTrustStore.verify({ promptCopy });
+
+			expect(result).toEqual({ kind: 'success' });
+		});
+
+		it('returns enrollmentChanged when Android raises KeyPermanentlyInvalidatedException', async () => {
+			mockedKeychain.hasGenericPassword.mockResolvedValueOnce(true);
+			mockedKeychain.getGenericPassword.mockRejectedValueOnce(new Error('KeyPermanentlyInvalidatedException'));
+
+			expect(await biometricTrustStore.verify({ promptCopy })).toEqual({ kind: 'enrollmentChanged' });
+		});
+
+		it('returns enrollmentChanged when iOS raises errSecItemNotFound after the prompt', async () => {
+			mockedKeychain.hasGenericPassword.mockResolvedValueOnce(true);
+			mockedKeychain.getGenericPassword.mockRejectedValueOnce({ code: '-25300', message: 'errSecItemNotFound' });
+
+			expect(await biometricTrustStore.verify({ promptCopy })).toEqual({ kind: 'enrollmentChanged' });
+		});
+
+		it('returns canceled when the user dismisses the prompt', async () => {
+			mockedKeychain.hasGenericPassword.mockResolvedValueOnce(true);
+			mockedKeychain.getGenericPassword.mockRejectedValueOnce({ message: 'errSecUserCancel' });
+
+			expect(await biometricTrustStore.verify({ promptCopy })).toEqual({ kind: 'canceled' });
+		});
+
+		it('forwards the prompt copy to keychain', async () => {
+			mockedKeychain.hasGenericPassword.mockResolvedValueOnce(true);
+			mockedKeychain.getGenericPassword.mockResolvedValueOnce({
+				service: 'svc',
+				username: 'biometric-trust',
+				password: 'v1',
+				storage: 'keychain'
+			} as any);
+
+			await biometricTrustStore.verify({ promptCopy });
+
+			const [options] = mockedKeychain.getGenericPassword.mock.calls[0];
+			expect(options).toMatchObject({ authenticationPrompt: { title: 'Authenticate', cancel: 'Cancel' } });
+		});
+	});
+});

app/lib/biometricTrustStore/index.ts

@@ -0,0 +1,107 @@
+import * as Keychain from 'react-native-keychain';
+
+export type TrustResult =
+	| { kind: 'success' }
+	| { kind: 'canceled' }
+	| { kind: 'enrollmentChanged' }
+	| { kind: 'unavailable' }
+	| { kind: 'error'; cause: unknown };
+
+export interface IBiometricTrustStore {
+	enrol(): Promise<TrustResult>;
+	disenrol(): Promise<void>;
+	verify(opts: { promptCopy: { title: string; cancel: string } }): Promise<TrustResult>;
+	probeExists(): Promise<boolean>;
+}
+
+const SENTINEL_SERVICE = 'chat.rocket.reactnative.biometric-trust';
+const SENTINEL_USERNAME = 'biometric-trust';
+const SENTINEL_VALUE = 'v1';
+
+// BIOMETRY_CURRENT_SET binds the item to the *current* biometric enrolment on both platforms; iOS
+// invalidates the keychain entry when the enrolment set changes (errSecItemNotFound on read), and
+// Android raises KeyPermanentlyInvalidatedException. That invalidation signal is the security
+// primitive this whole module exists for.
+const writeOptions = (): Keychain.SetOptions => ({
+	service: SENTINEL_SERVICE,
+	accessControl: Keychain.ACCESS_CONTROL.BIOMETRY_CURRENT_SET,
+	accessible: Keychain.ACCESSIBLE.WHEN_UNLOCKED_THIS_DEVICE_ONLY
+});
+
+const readOptions = (promptCopy: { title: string; cancel: string }): Keychain.GetOptions => ({
+	service: SENTINEL_SERVICE,
+	authenticationPrompt: {
+		title: promptCopy.title,
+		cancel: promptCopy.cancel
+	}
+});
+
+// errSecUserCancel — biometric prompt dismissed by the user.
+// errSecItemNotFound (-25300) when raised *after* the OS prompt indicates the keychain item was
+// invalidated by an enrollment change on iOS.
+// KeyPermanentlyInvalidatedException is the Android signal for the same condition.
+export const classifyError = (e: unknown): TrustResult => {
+	const err = e as { code?: string | number; name?: string; message?: string } | null | undefined;
+	const code = err?.code != null ? String(err.code) : '';
+	const name = err?.name ?? '';
+	const message = err?.message ?? '';
+	const blob = `${code} ${name} ${message}`;
+
+	if (/errSecUserCancel|UserCancel|user.?cancel|AuthenticationCanceled|-128\b/i.test(blob)) {
+		return { kind: 'canceled' };
+	}
+	if (/KeyPermanentlyInvalidatedException/i.test(blob)) {
+		return { kind: 'enrollmentChanged' };
+	}
+	if (/errSecItemNotFound|-25300/i.test(blob)) {
+		return { kind: 'enrollmentChanged' };
+	}
+	return { kind: 'error', cause: e };
+};
+
+export const biometricTrustStore: IBiometricTrustStore = {
+	async enrol() {
+		try {
+			await Keychain.setGenericPassword(SENTINEL_USERNAME, SENTINEL_VALUE, writeOptions());
+			return { kind: 'success' };
+		} catch (e) {
+			return classifyError(e);
+		}
+	},
+
+	async disenrol() {
+		try {
+			await Keychain.resetGenericPassword({ service: SENTINEL_SERVICE });
+		} catch {
+			// best-effort delete; sentinel may already be absent
+		}
+	},
+
+	async verify({ promptCopy }) {
+		const exists = await biometricTrustStore.probeExists();
+		if (!exists) {
+			return { kind: 'unavailable' };
+		}
+		try {
+			const result = await Keychain.getGenericPassword(readOptions(promptCopy));
+			if (result && result.password === SENTINEL_VALUE) {
+				return { kind: 'success' };
+			}
+			// OS prompt succeeded but the sentinel is gone — treat as enrollment change.
+			return { kind: 'enrollmentChanged' };
+		} catch (e) {
+			return classifyError(e);
+		}
+	},
+
+	async probeExists() {
+		try {
+			const result = await Keychain.hasGenericPassword({ service: SENTINEL_SERVICE });
+			return !!result;
+		} catch {
+			return false;
+		}
+	}
+};
+
+export default biometricTrustStore;

app/lib/methods/helpers/events.ts

@@ -10,6 +10,7 @@ type TEventEmitterEmmitArgs =
 	| { invalid: boolean }
 	| { force: boolean }
 	| { hasBiometry: boolean }
+	| { skipAutoBiometry: boolean }
 	| { visible: boolean; onCancel?: null | Function }
 	| { cancel: () => void }
 	| { submit: (param: string) => void }

app/lib/methods/helpers/localAuthentication.ts

@@ -8,6 +8,7 @@ import UserPreferences from '../userPreferences';
 import { store } from '../../store/auxStore';
 import database from '../../database';
 import { getServerTimeSync } from '../../services/getServerTimeSync';
+import { biometricTrustStore, type TrustResult } from '../../biometricTrustStore';
 import {
 	ATTEMPTS_KEY,
 	BIOMETRY_ENABLED_KEY,
@@ -50,12 +51,13 @@ export const saveLastLocalAuthenticationSession = async (
 
 export const resetAttempts = (): Promise<void> => AsyncStorage.multiRemove([LOCKED_OUT_TIMER_KEY, ATTEMPTS_KEY]);
 
-const openModal = (hasBiometry: boolean, force?: boolean) =>
+const openModal = (hasBiometry: boolean, force?: boolean, skipAutoBiometry?: boolean) =>
 	new Promise<void>((resolve, reject) => {
 		EventEmitter.emit(LOCAL_AUTHENTICATE_EMITTER, {
 			submit: () => resolve(),
 			hasBiometry,
 			force,
+			skipAutoBiometry,
 			cancel: () => reject()
 		});
 	});
@@ -74,20 +76,21 @@ export const changePasscode = async ({ force = false }: { force: boolean }): Pro
 	UserPreferences.setString(PASSCODE_KEY, sha256(passcode));
 };
 
-export const biometryAuth = (force?: boolean): Promise<LocalAuthentication.LocalAuthenticationResult> =>
-	LocalAuthentication.authenticateAsync({
-		disableDeviceFallback: true,
-		cancelLabel: force ? I18n.t('Dont_activate') : I18n.t('Local_authentication_biometry_fallback'),
-		promptMessage: I18n.t('Local_authentication_biometry_title')
-	});
+const buildPromptCopy = (force?: boolean) => ({
+	title: I18n.t('Local_authentication_biometry_title'),
+	cancel: force ? I18n.t('Dont_activate') : I18n.t('Local_authentication_biometry_fallback')
+});
+
+export const biometryAuth = (force?: boolean): Promise<TrustResult> =>
+	biometricTrustStore.verify({ promptCopy: buildPromptCopy(force) });
 
 /*
  * It'll help us to get the permission to use FaceID
  * and enable/disable the biometry when user put their first passcode
  */
 const checkBiometry = async () => {
-	const result = await biometryAuth(true);
-	const isBiometryEnabled = !!result?.success;
+	const result = await biometricTrustStore.enrol();
+	const isBiometryEnabled = result.kind === 'success';
 	UserPreferences.setBool(BIOMETRY_ENABLED_KEY, isBiometryEnabled);
 	return isBiometryEnabled;
 };
@@ -111,17 +114,31 @@ const hideSplashScreen = async () => {
 };
 
 export const handleLocalAuthentication = async (canCloseModal = false) => {
-	// let hasBiometry = false;
-	let hasBiometry = UserPreferences.getBool(BIOMETRY_ENABLED_KEY) ?? false;
+	const biometryEnabled = UserPreferences.getBool(BIOMETRY_ENABLED_KEY) ?? false;
+
+	if (!biometryEnabled) {
+		await openModal(false, canCloseModal);
+		return;
+	}
+
+	const result = await biometricTrustStore.verify({ promptCopy: buildPromptCopy() });
+
+	// success → unlocked, no modal
+	if (result.kind === 'success') {
+		return;
+	}
 
-	// if biometry is enabled on the app
-	if (hasBiometry) {
-		const isEnrolled = await LocalAuthentication.isEnrolledAsync();
-		hasBiometry = isEnrolled;
+	// canceled / error → user dismissed or the OS prompt failed; keep biometry available on the
+	// modal but skip the auto-prompt so we don't immediately re-fire the same prompt the user
+	// just dismissed.
+	if (result.kind === 'canceled' || result.kind === 'error') {
+		await openModal(true, canCloseModal, true);
+		return;
 	}
 
-	// Authenticate
-	await openModal(hasBiometry, canCloseModal);
+	// unavailable / enrollmentChanged → no usable sentinel; passcode-only modal. Slice 02 will
+	// add disenrol() + flag-clear + an explanatory reason for the enrollmentChanged case.
+	await openModal(false, canCloseModal);
 };
 
 export const localAuthenticate = async (server: string): Promise<void> => {