Authentication & Device Binding
==================================

WORKVO provides enterprise-grade identity verification, combining tenant-isolated credentials with hardware-level cryptographic device binding.

.. contents:: Table of Contents
   :local:
   :depth: 2

Role Selection Screen
---------------------
When users open WORKVO for the first time or switch operational roles, they are presented with the Role Selection interface.

.. image:: _static/screenshots/02_role_selection.png
   :width: 320px
   :align: center
   :alt: Role Selection Screen

Available Portals
~~~~~~~~~~~~~~~~~
1. **Business Manager / Admin**:
   - Access to team approvals, employee shift overrides, leave grants, payroll calculations, and diagnostic reports.
2. **Regular Staff Member**:
   - Streamlined geofenced punch in/out, selfie capture, leave balance tracking, payslip downloads, and company holiday calendar.
3. **Field Sales Specialist**:
   - Real-time GPS breadcrumbs, client visit check-ins, travel allowance (TA) logging, and battery-optimized instant punching.

Employee Sign-In Screen
-----------------------
The unified sign-in screen securely connects to the company's designated instance.

.. image:: _static/screenshots/03_login_screen.png
   :width: 320px
   :align: center
   :alt: Employee Login Screen

Authentication Features
~~~~~~~~~~~~~~~~~~~~~~~
* **Company Instance Routing**: Auto-discovers API endpoint and tenant settings via company code.
* **Biometric Quick Unlock**: Integrates with local device Android BiometricPrompt and iOS Face ID / Touch ID.
* **Session Persistence**: Refresh tokens stored securely in Android Keystore / iOS Keychain.

Single-Device Hardware Binding
------------------------------
To eliminate proxy punching and buddy clock-ins, WORKVO binds each employee account to a single physical device:

.. image:: _static/screenshots/09_device_approvals.png
   :width: 320px
   :align: center
   :alt: Device Approval Screen

How Hardware Binding Works
~~~~~~~~~~~~~~~~~~~~~~~~~~
1. Upon initial login, `DeviceIdentityHelper` generates a hardware signature:
   - Device Manufacturer & Model (e.g., `Samsung Galaxy S23`)
   - Operating System Version (`Android 14 / SDK 34`)
   - Unique Hardware UUID hash
2. If the user logs in from a new or unapproved device, the login is blocked and flagged as **Pending Approval**.
3. The Manager receives an immediate notification in the **Device Approvals** screen to review the device details and grant or reject access.