feat(mobile): security settings for lock timeout and biometric unlock

[Elizabethxxx]

Lets users tune the app-lock behaviour: the inactivity timeout and whether unlocking requires biometrics.

closes #491

What is here

• frontend/mobile/lib/appLock.ts — the policy store and createIdleWatcher, the countdown the lock screen (backlog feat(sdk): expose guardian recovery methods (setGuardian, initiateRecovery, completeRecovery) #28) wires to.
• frontend/mobile/hooks/useAppLock.ts — subscribes a component to the policy, following the same shape as the existing useTheme.
• frontend/mobile/app/settings/security.tsx — the screen: four timeout options and a biometric switch.
• 22 tests.

Acceptance: changing the timeout changes lock behaviour

A running watcher subscribes to the settings store, so a change reschedules it immediately rather than taking effect at the next lock. Both directions are covered:

• Lengthening 5 → 30 minutes four minutes in: the old deadline passes without a lock, the new one fires.
• Shortening 30 → 5 minutes six minutes in: six minutes idle already exceeds the new policy, so the lock is due at once rather than at the old deadline.
• Switching to "never" cancels a pending lock outright.

Design notes

The timeout shares the web wallet's storage key (veil_idle_lock_minutes) and offers the same four options. The setting is shared across clients, so an option that existed on only one of them would be silently rewritten by the other.

Backgrounding is not activity. The web wallet treats visibilitychange as activity and resets the timer. On a phone the equivalent means something stronger: JS timers are frozen or killed while the app is away, so a timer alone would let a phone sit in a pocket for an hour and come back unlocked. The watcher records when the app left the foreground and, on return, locks if the idle period already elapsed.

Activity is reported explicitly via noteActivity(), since React Native has no global mouse/keyboard/scroll stream to listen to the way window does.

The biometric requirement is stored as a preference, not gated on a capability check. Whether a device has usable biometrics can change between setting the toggle and the unlock, so the lock screen resolves that when it prompts and falls back to the passkey rather than locking a user out of their own funds. The screen says so.

Deferral is carried over from the web watcher: shouldDefer postpones a lock rather than interrupting an in-flight transaction.

Scope

This is the settings half of the lock system — it decides when a lock is due and how strong the unlock must be. Presenting the lock screen and performing the unlock is backlog #28, which consumes createIdleWatcher and getLockSettings rather than reimplementing either. That is why the behaviour is demonstrated by tests against the watcher instead of by a lock screen appearing.

Checks

npm run typecheck and npm test pass in frontend/mobile.

[vercel]

@Elizabethxxx is attempting to deploy a commit to the miracle656's projects Team on Vercel.

A member of the Team first needs to authorize it.

[drips-wave]

@Elizabethxxx Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[Miracle656]

Merging. lib/appLock.ts follows the same shape as the network module — typed settings, a subscription so screens re-render, hydration from AsyncStorage — and 408 lines of tests around a 313-line module is a good ratio for something guarding funds. Modelling 'never' as a first-class LockTimeout variant rather than a magic 0 is the right call.

Two things had to be fixed for the settings to actually do anything:

hydrateLockSettings() was never called. Exactly the same gap #526 had with the network override: settings were written to AsyncStorage and a hydrate function existed, but nothing invoked it, so every launch started on DEFAULT_LOCK_TIMEOUT and a saved choice only applied once the user went back and re-picked it. Now called from app/_layout.tsx next to hydrateNetwork().

/settings/security was unreachable. The settings tab renders its rows as Pressables whose onPress only sets local state — there's a "Security & lock" row, but tapping it went nowhere. SettingsRow now takes an optional href and navigates when one is present, with that row pointing at the new screen. The other rows keep their existing behaviour until their own screens land.

Verified: tsc --noEmit clean, jest 15 suites / 266 tests, expo lint clean, CI green.

On the acceptance criterion — changing timeout changes lock behavior — the settings half is now complete and persisted, but the consumer isn't here yet: backlog #28's actual lock screen is #596, still open. So lockTimeoutToMs() currently has no caller enforcing it. Worth re-testing this end to end once #596 lands; the storage keys (veil_idle_lock_minutes, veil_lock_require_biometrics) and subscribeToLockSettings are the contract it should read from.

Also worth noting for whoever picks up #596: DEFAULT_REQUIRE_BIOMETRICS is false, so biometric unlock is opt-in. That's a defensible default for a wallet that already sits behind device unlock, but it's a product decision worth making deliberately rather than inheriting.