Biometric Lock

ZestSSH supports biometric authentication to protect the app from unauthorized access. This is a free feature — security is not paywalled.

Supported Biometrics

Platform	Methods
iOS	Face ID, Touch ID
Android	Fingerprint, face unlock, iris scan (device-dependent)
macOS	Touch ID (on supported hardware)

Biometric support is provided by the local_auth Flutter package, which delegates to the platform’s native biometric APIs:

• iOS: LocalAuthentication framework
• Android: BiometricPrompt API
• macOS: LocalAuthentication framework

How It Works

Availability Check

Before offering biometric lock, ZestSSH checks two conditions:

1. canCheckBiometrics — The device has biometric hardware.
2. isDeviceSupported — The device supports the platform’s authentication mechanism.

Both must be true for biometric lock to be available. If either check fails (or throws a PlatformException), the biometric option is hidden in settings.

Authentication Flow

When the app is locked and biometric authentication is configured:

1. The system biometric dialog appears with the prompt: “Authenticate to unlock ZestSSH”.
2. The user authenticates with their face, fingerprint, or other enrolled biometric.
3. On success, the app unlocks.
4. On failure, the user can retry or fall back to PIN.

Authentication options:

• stickyAuth: true — The authentication dialog persists until the user explicitly cancels. It does not dismiss on app switch.
• biometricOnly: true — Only biometric methods are accepted (no device PIN/password fallback at the system level).

Lock Methods

ZestSSH supports four lock method configurations:

Method	Behavior
none	No lock (default)
biometric	Biometric only
pin	PIN only (see PIN Lock)
both	Biometric with PIN fallback

When set to both, the user is first prompted for biometric authentication. If biometric fails or is cancelled, the PIN entry screen appears as a fallback.

Auto-Lock Timeout

Configure how quickly the app locks after going to the background:

• Immediate (0 minutes) — Locks as soon as the app is backgrounded.
• 1 minute (default) — Locks after 1 minute in the background.
• Custom timeout in minutes.

The timeout is stored in secure storage under the key security_auto_lock_timeout.

Setup

1. Go to Settings > Security.
2. Under App Lock, select Biometric or Biometric + PIN.
3. Authenticate with your biometric to confirm enrollment.
4. If selecting Biometric + PIN, you will also be prompted to set a PIN.

Platform Notes

iOS

• Face ID requires the NSFaceIDUsageDescription key in Info.plist.
• Touch ID works on iPhone SE, iPhone 8, and iPads with a Home button.
• If the user has not enrolled any biometrics, the option is unavailable.

Android

• Requires android.permission.USE_BIOMETRIC in the manifest.
• The system BiometricPrompt handles all UI rendering — ZestSSH does not draw its own biometric dialog.
• On Android 9 and below, falls back to the legacy fingerprint API.

macOS

• Touch ID is available on MacBook Pro (2016+) and MacBook Air (2018+) with the Touch Bar or power button sensor.
• Requires the com.apple.security.keychain-access-groups entitlement.

Security Considerations

• Biometric data never leaves the device — ZestSSH does not access or store biometric templates.
• The local_auth package uses the OS-level biometric APIs, which are backed by the Secure Enclave (iOS/macOS) or TEE/StrongBox (Android).
• The lock method is stored in Flutter Secure Storage (encrypted by the platform keystore), not in plaintext SharedPreferences.
• Biometric authentication state is not persisted — the app always re-authenticates after the auto-lock timeout expires.