Biometric App Lock

What Is App Lock?

App Lock (Spec 178) is a device-level screen that appears when you reopen the Helm app after it has been idle. To pass it, you use your device's Face ID, Touch ID, or a 6-digit PIN you set inside Helm. No internet connection is needed to unlock.

App Lock protects the content already loaded on your device — your tasks, journal, messages, and partner data — from someone who picks up your unlocked phone. It does not change your Helm account password, and it has no effect on the web version of Helm.

App Lock vs. Login Biometrics

Helm has two separate biometric features. They serve different purposes and are configured independently:

• Login biometrics (Spec 008 — Touch ID / Face ID to log in): replaces typing your email and password when you start a new session. This is a WebAuthn credential tied to your Helm account. It does not protect an already-open session.
• App Lock (Spec 178 — this feature): activates after the app has been idle for a configurable time and locks the open session itself. It uses a 6-digit PIN stored on your device, with biometric unlock as a shortcut. Your Helm account credentials are not involved.

Feature Flag and Availability

App Lock is gated behind the biometricAppLock feature flag. The App Privacy accordion in Account Settings is only visible when this flag is enabled for your organization. If you do not see it, the feature is not yet active for your account.

Enabling App Lock

1. Open Account Settings
   Tap your profile or navigate to Account Settings in the app.
2. Open the Security section
   Expand the Security accordion. Scroll to the App Privacy sub-section.
3. Toggle App lock on
   Tap the App lock toggle. Because a PIN is required before lock can be active, the PIN setup flow launches immediately.
4. Set your PIN
   Enter a 6-digit PIN using the numeric keypad. You are prompted to enter it a second time to confirm. If the two entries do not match, you are asked to try again from the beginning. When both entries match, the PIN is saved and App Lock becomes active.
5. Choose a lock timeout
   Once enabled, a "Lock after" dropdown appears. Choose how long the app must be in the background before it locks. The default is 5 minutes.

Lock Timeout Options

• Immediately — locks as soon as the app goes to background
• 1 minute
• 5 minutes (default)
• 15 minutes
• 30 minutes
• 1 hour
• Never — App Lock is enabled but the lock screen never triggers automatically; you can still use "Lock Now"

Additional Controls When App Lock Is On

• Change PIN: reopens the PIN setup flow to replace your current PIN
• Lock Now: immediately activates the lock screen without waiting for the idle timeout. This button is unavailable during an active safeword.

How the Lock Screen Works

When the app returns to the foreground after the idle timeout has elapsed, a full-screen overlay appears over all app content. The Helm logo is displayed and the text "Helm is locked" is shown. The overlay cannot be dismissed by tapping the background, pressing Escape, or swiping — it must be unlocked.

Biometric Unlock

By default the overlay shows a button labeled "Unlock with Face ID / Touch ID." Tapping it triggers your device's native biometric authentication prompt. On success, the overlay is removed and any queued audit events are flushed to the server.

After three consecutive biometric failures, the overlay automatically switches to PIN entry. You can also skip biometric and go directly to the PIN at any time by tapping "Use PIN instead."

PIN Entry

The PIN entry screen shows the same numeric keypad used during setup, with dot indicators for each of the 6 digits. The PIN is compared against a salted SHA-256 hash stored in your device's secure credential store — it is never sent over the network to unlock. On a correct PIN, the overlay is removed.

Too Many Attempts

After repeated failed PIN entries the overlay transitions to a locked-out state with the message "Too many attempts. Please use account recovery to reset your PIN." Use the "Forgot PIN" link described below to recover access.

PIN Recovery via Email

If you cannot unlock the app and are locked out, tap "Forgot PIN" on the lock screen. This opens https://helmapp.co/account/app-lock-recovery in your device's system browser, where you can complete an email-based recovery flow.

The recovery process works as follows:

1. Request recovery on the web
   On the recovery page, verify your identity using your email address. The server marks a recovery-pending flag on your account.
2. Return to the Helm app
   Switch back to Helm. On the next foreground event, the app checks for a pending recovery flag.
3. Credentials are cleared automatically
   If a recovery is pending, the app clears all App Lock credentials (PIN hash, salt, idle timeout setting), acknowledges the recovery on the server, and disables App Lock. You are returned to the normal app without a lock screen.
4. Re-enable App Lock
   If you want App Lock back, go to Account Settings and set a new PIN following the enable steps above.

Disabling App Lock

To turn App Lock off when you can still unlock the screen normally:

1. Unlock the app using biometric or PIN
2. Go to Account Settings → Security → App Privacy
3. Toggle App lock off

Disabling App Lock removes the PIN credential from your device's secure store and clears all stored lock settings. You will not be prompted to unlock the next time you open Helm.

Audit Logging

Every successful unlock attempt is logged to your Helm account. If a network request fails at unlock time, the event is queued locally on the device and flushed the next time the app successfully connects to the server. This ensures the audit log reflects the actual unlock history even under intermittent connectivity.

Audit events are not currently exposed in the app UI. They are available to Helm support for account-recovery and security investigations.