feat(biometric-trust): silent-bind migration for existing biometry users on upgrade

Existing installs that had biometry enabled before the trust store existed
have BIOMETRY_ENABLED_KEY=true but no keychain sentinel, which would force
them through the passcode-only modal on first launch after upgrade. Run a
one-shot migration on app init that grandfathers them with a silent enrol().

The marker BIOMETRIC_TRUST_MIGRATION_V1_DONE makes this idempotent and lets
the helper distinguish two superficially identical states:

  !migrated && flag && !sentinel → silent enrol(), set marker.    upgrade path
   migrated && flag && !sentinel → clear flag, no enrol().        reconciliation

Without the marker, post-invalidation state (flag=true && !sentinel after a
crash between disenrol() and the flag-clear in the enrollmentChanged
handler) would silently re-bind and undo the enrollment-change protection.
With the marker, that state instead clears the flag — the user re-enables
biometry from Settings, which runs a fresh enrol() that observes the new
enrolment set.

enrol() failure leaves the marker unset so the next boot retries, and
leaves the flag alone so the next unlock falls into the unavailable branch
and asks for the passcode. probeExists() rejection is swallowed and logged.

The trade-off (silent bind vs. theoretical pre-fix compromise) follows the
product decision in DECISIONS.md / ADR 0006.

Part of VLN-216.

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

Author: OtavioStasiak

app/lib/biometricTrustStore/migration.test.ts

@@ -0,0 +1,135 @@
+import UserPreferences from '../methods/userPreferences';
+import log from '../methods/helpers/log';
+import { BIOMETRIC_TRUST_MIGRATION_V1_DONE, BIOMETRY_ENABLED_KEY } from '../constants/localAuthentication';
+import { biometricTrustStore } from './index';
+import { runBiometricTrustMigration } from './migration';
+
+jest.mock('../methods/userPreferences', () => ({
+	__esModule: true,
+	default: {
+		getBool: jest.fn(),
+		setBool: jest.fn(),
+		getString: jest.fn(),
+		setString: jest.fn()
+	}
+}));
+
+jest.mock('../methods/helpers/log', () => ({ __esModule: true, default: jest.fn() }));
+
+jest.mock('./index', () => ({
+	biometricTrustStore: {
+		enrol: jest.fn(),
+		disenrol: jest.fn(),
+		verify: jest.fn(),
+		probeExists: jest.fn()
+	}
+}));
+
+const mockedGetBool = UserPreferences.getBool as jest.Mock;
+const mockedSetBool = UserPreferences.setBool as jest.Mock;
+const mockedEnrol = biometricTrustStore.enrol as jest.Mock;
+const mockedProbeExists = biometricTrustStore.probeExists as jest.Mock;
+const mockedLog = log as unknown as jest.Mock;
+
+// Drives the mocked UserPreferences with the values the migration needs to see for the
+// branch under test, so each test reads like a state machine input row.
+const setPrefs = ({ biometryEnabled, migrated }: { biometryEnabled: boolean; migrated: boolean }) => {
+	mockedGetBool.mockImplementation((key: string) => {
+		if (key === BIOMETRY_ENABLED_KEY) return biometryEnabled;
+		if (key === BIOMETRIC_TRUST_MIGRATION_V1_DONE) return migrated;
+		return undefined;
+	});
+};
+
+describe('runBiometricTrustMigration', () => {
+	beforeEach(() => {
+		jest.clearAllMocks();
+	});
+
+	it('upgrade path: !migrated && flag && !sentinel → enrol() once and mark migrated', async () => {
+		setPrefs({ biometryEnabled: true, migrated: false });
+		mockedProbeExists.mockResolvedValueOnce(false);
+		mockedEnrol.mockResolvedValueOnce({ kind: 'success' });
+
+		await runBiometricTrustMigration();
+
+		expect(mockedEnrol).toHaveBeenCalledTimes(1);
+		expect(mockedSetBool).toHaveBeenCalledWith(BIOMETRIC_TRUST_MIGRATION_V1_DONE, true);
+		expect(mockedSetBool).not.toHaveBeenCalledWith(BIOMETRY_ENABLED_KEY, false);
+	});
+
+	it('reconciliation path: migrated && flag && !sentinel → clear flag, no enrol()', async () => {
+		setPrefs({ biometryEnabled: true, migrated: true });
+		mockedProbeExists.mockResolvedValueOnce(false);
+
+		await runBiometricTrustMigration();
+
+		expect(mockedEnrol).not.toHaveBeenCalled();
+		expect(mockedSetBool).toHaveBeenCalledWith(BIOMETRY_ENABLED_KEY, false);
+		expect(mockedSetBool).not.toHaveBeenCalledWith(BIOMETRIC_TRUST_MIGRATION_V1_DONE, expect.anything());
+	});
+
+	it('flag=false → no-op (no probe, no enrol, no setBool)', async () => {
+		setPrefs({ biometryEnabled: false, migrated: false });
+
+		await runBiometricTrustMigration();
+
+		expect(mockedProbeExists).not.toHaveBeenCalled();
+		expect(mockedEnrol).not.toHaveBeenCalled();
+		expect(mockedSetBool).not.toHaveBeenCalled();
+	});
+
+	it('flag=true && sentinel exists → no-op (no enrol, no flag clear)', async () => {
+		setPrefs({ biometryEnabled: true, migrated: false });
+		mockedProbeExists.mockResolvedValueOnce(true);
+
+		await runBiometricTrustMigration();
+
+		expect(mockedEnrol).not.toHaveBeenCalled();
+		expect(mockedSetBool).not.toHaveBeenCalled();
+	});
+
+	it('idempotent: after successful migration, second run is a no-op', async () => {
+		// first run: upgrade path
+		setPrefs({ biometryEnabled: true, migrated: false });
+		mockedProbeExists.mockResolvedValueOnce(false);
+		mockedEnrol.mockResolvedValueOnce({ kind: 'success' });
+		await runBiometricTrustMigration();
+		expect(mockedEnrol).toHaveBeenCalledTimes(1);
+
+		// second run: sentinel now exists AND marker is set
+		jest.clearAllMocks();
+		setPrefs({ biometryEnabled: true, migrated: true });
+		mockedProbeExists.mockResolvedValueOnce(true);
+
+		await runBiometricTrustMigration();
+
+		expect(mockedEnrol).not.toHaveBeenCalled();
+		expect(mockedSetBool).not.toHaveBeenCalled();
+	});
+
+	it('enrol() error → logged, flag untouched, marker NOT set so next boot retries', async () => {
+		setPrefs({ biometryEnabled: true, migrated: false });
+		mockedProbeExists.mockResolvedValueOnce(false);
+		const cause = new Error('keychain unavailable');
+		mockedEnrol.mockResolvedValueOnce({ kind: 'error', cause });
+
+		await runBiometricTrustMigration();
+
+		expect(mockedLog).toHaveBeenCalledWith(cause);
+		expect(mockedSetBool).not.toHaveBeenCalledWith(BIOMETRIC_TRUST_MIGRATION_V1_DONE, expect.anything());
+		expect(mockedSetBool).not.toHaveBeenCalledWith(BIOMETRY_ENABLED_KEY, false);
+	});
+
+	it('probeExists throws → swallowed, logged, no enrol(), no flag mutation', async () => {
+		setPrefs({ biometryEnabled: true, migrated: false });
+		const boom = new Error('probe failed');
+		mockedProbeExists.mockRejectedValueOnce(boom);
+
+		await runBiometricTrustMigration();
+
+		expect(mockedLog).toHaveBeenCalledWith(boom);
+		expect(mockedEnrol).not.toHaveBeenCalled();
+		expect(mockedSetBool).not.toHaveBeenCalled();
+	});
+});

app/lib/biometricTrustStore/migration.ts

@@ -0,0 +1,48 @@
+import UserPreferences from '../methods/userPreferences';
+import log from '../methods/helpers/log';
+import { BIOMETRIC_TRUST_MIGRATION_V1_DONE, BIOMETRY_ENABLED_KEY } from '../constants/localAuthentication';
+import { biometricTrustStore } from './index';
+
+// One-shot upgrade migration for users who had biometry enabled before the trust-store sentinel
+// existed. Runs at app init.
+//
+// State machine:
+//   !migrated && flag && !sentinel → silent enrol(), mark migrated.   (grandfather upgrade path)
+//    migrated && flag && !sentinel → clear flag, do NOT enrol().      (reconciliation, e.g. crash
+//                                                                      between disenrol() and the
+//                                                                      flag-clear during slice 02
+//                                                                      invalidation)
+//    flag && sentinel               → no-op.
+//   !flag                           → no-op.
+//
+// On enrol() failure the marker is intentionally left unset so the next boot retries; the flag is
+// left as-is so the next unlock falls into the `unavailable` branch and asks for the passcode.
+export const runBiometricTrustMigration = async (): Promise<void> => {
+	try {
+		const biometryEnabled = UserPreferences.getBool(BIOMETRY_ENABLED_KEY) ?? false;
+		if (!biometryEnabled) {
+			return;
+		}
+
+		const sentinelExists = await biometricTrustStore.probeExists();
+		if (sentinelExists) {
+			return;
+		}
+
+		const migrated = UserPreferences.getBool(BIOMETRIC_TRUST_MIGRATION_V1_DONE) ?? false;
+
+		if (!migrated) {
+			const result = await biometricTrustStore.enrol();
+			if (result.kind === 'success') {
+				UserPreferences.setBool(BIOMETRIC_TRUST_MIGRATION_V1_DONE, true);
+			} else if (result.kind === 'error') {
+				log(result.cause);
+			}
+			return;
+		}
+
+		UserPreferences.setBool(BIOMETRY_ENABLED_KEY, false);
+	} catch (e) {
+		log(e);
+	}
+};

app/lib/constants/localAuthentication.ts

@@ -2,6 +2,7 @@ export const PASSCODE_KEY = 'kPasscode';
 export const LOCKED_OUT_TIMER_KEY = 'kLockedOutTimer';
 export const ATTEMPTS_KEY = 'kAttempts';
 export const BIOMETRY_ENABLED_KEY = 'kBiometryEnabled';
+export const BIOMETRIC_TRUST_MIGRATION_V1_DONE = 'kBiometricTrustMigrationV1Done';
 
 export const LOCAL_AUTHENTICATE_EMITTER = 'LOCAL_AUTHENTICATE';
 export const CHANGE_PASSCODE_EMITTER = 'CHANGE_PASSCODE';

app/sagas/init.js

@@ -10,6 +10,7 @@ import { APP } from '../actions/actionsTypes';
 import log from '../lib/methods/helpers/log';
 import database from '../lib/database';
 import { localAuthenticate } from '../lib/methods/helpers/localAuthentication';
+import { runBiometricTrustMigration } from '../lib/biometricTrustStore/migration';
 import { appReady, appStart } from '../actions/app';
 import { RootEnum } from '../definitions';
 import { getSortPreferences } from '../lib/methods/userPreferencesMethods';
@@ -23,6 +24,7 @@ export const initLocalSettings = function* initLocalSettings() {
 
 const restore = function* restore() {
 	try {
+		yield call(runBiometricTrustMigration);
 		const server = UserPreferences.getString(CURRENT_SERVER);
 		let userId = UserPreferences.getString(`${TOKEN_KEY}-${server}`);