Skip to main content
App Lock places a no-PHI lock screen in front of the authenticated app whenever you background the tab or stay idle past your inactivity timeout. You unlock with a 6-digit PIN, a platform biometric, or by signing in again — no patient information is shown until you do.

​
Overview

App Lock is a client-side surface in the authenticated shell. When the lock engages, an overlay covers route content in place — there is no separate /lock route. Your session, navigation state, and unsaved work in memory are preserved. Lock state, the PIN-derived key, and your local policy are stored in sessionStorage only and are cleared when the tab closes. Lock and unlock events are written to the audit log without PHI. App Lock applies to the staff app at /settings/security. Portal patients manage MFA on their own Security Settings page.

​
Who it’s for

Any signed-in staff user. There is no permission gate — every user can configure their own App Lock policy and PIN. Organization admins can also enforce lock-on-mobile and a maximum inactivity timeout. When that policy is set, the enforced values override your local preferences.

​
Before you start

  • Sign in to the staff app.
  • For biometric unlock, use a browser and device that support WebAuthn platform authenticators (Touch ID, Face ID, Windows Hello, Android biometrics).
  • Review the in-app notice: the PIN-derived key is stored in sessionStorage for the current tab only. It is defense-in-depth and does not satisfy HIPAA encryption-at-rest on its own.

​
Steps

1

Open Security settings

Go to Settings → Security (/settings/security). The App Lock section appears alongside MFA settings.
2

Set an app PIN

Select Set PIN, enter a 6-digit numeric PIN, and confirm it. The app derives a PBKDF2 key from your PIN and stores only the derived value — the raw PIN is never sent to the server.
3

Choose when to lock

Turn on Lock when app is backgrounded to engage the lock as soon as the tab loses visibility. Set Inactivity timeout to the number of minutes of no interaction before the app locks.
4

Enable biometric unlock (optional)

Select Use biometric to unlock and complete the platform biometric prompt to enroll. The option only appears on supported devices. Raw biometric data never leaves the device.
5

Verify the lock

Switch tabs or wait out the inactivity timeout. The lock screen should appear with no PHI visible. Unlock with your PIN, biometric, or Sign in again.

​
Unlocking

The lock screen offers three actions, depending on what you have configured and what the device supports:
  • Enter PIN — Type your 6-digit PIN. After 5 incorrect attempts, PIN entry is paused for 30 seconds. After 3 lockout cycles in the same session, the app escalates to a full sign-in.
  • Use biometric — Shown when biometric unlock is enabled and supported. On failure or when biometric is unavailable, fall back to PIN entry or full sign-in.
  • Sign in again / Lock and sign out — Clears the Supabase session and returns you to the login screen. Use this on shared or unattended devices.
In a PWA context where WebAuthn is unavailable and PHI access is required, the lock screen only offers Sign in again — PIN-only unlock is not allowed in that mode.

​
Organization policy

Org admins can enforce App Lock for mobile clients through Platform settings: When policy is enforced, the relevant controls on Settings → Security display the enforced value and cannot be relaxed.

​
Audit events

App Lock writes the following fire-and-forget audit events (no PHI):
  • app_locked, app_unlocked
  • app_pin_failed_attempt, app_pin_lockout
  • app_biometric_enrolled, app_biometric_disabled
  • app_biometric_unlock_success, app_biometric_unlock_failed
Review them in Audit logs or Security events.

​
Example: enforce a 5-minute mobile lock

An admin sets the org policy so every mobile session locks after 5 minutes of inactivity, even if a user prefers a longer timeout:
After the policy syncs, mobile clients show the enforced 5-minute timeout in Settings → Security and lock at that interval regardless of the user’s local preference.

​
Key concepts

Lock trigger — The condition that engages the overlay. Two triggers ship today: the Page Visibility API (background/foreground transitions) and an inactivity timer driven by user input events. PIN-derived key — A PBKDF2-derived value stored in sessionStorage. Used for constant-time PIN verification on the device. The raw PIN is never persisted or transmitted. Escalation to full re-login — After repeated PIN lockouts in the same session, the app forces a Supabase sign-out and returns the user to the login screen. No-PHI lock screen — The overlay never renders patient identifiers, route content, or cached data. On any internal error, the lock fails secure (stays locked).

Security Settings (portal)

Patient portal MFA management.

Sessions & Devices

Review active sessions and trusted devices.

Security events

Audit-backed security event feed.

Audit logs

Full audit log with lock/unlock events.
This page documents shipped product behavior. It is not medical, legal, or billing advice. Verify against your organization’s policies and applicable regulations before using it for clinical, compliance, or billing decisions. Protected health information (PHI) shown in the product is governed by your tenant’s access controls and is never exposed in this documentation.
  • src/platform/auth/app-lock/AppLockContext.tsx
  • src/platform/auth/app-lock/AppLockGate.tsx
  • src/platform/auth/app-lock/LockScreenOverlay.tsx
  • src/platform/auth/app-lock/PinSetupDialog.tsx
  • src/platform/auth/app-lock/AppLockSettingsSection.tsx
  • src/platform/auth/app-lock/useAppLockState.ts
  • src/platform/auth/app-lock/useVisibilityAndInactivityLockTrigger.ts
  • src/platform/auth/app-lock/biometric-utils.ts
  • src/platform/auth/app-lock/pin-utils.ts
  • src/platform/settings/SecuritySettingsPage.tsx