Device Binding

Purpose

Prevent buddy punching. Ties an employee's check-ins to approved hardware.

Fingerprint

The Flutter app computes a stable fingerprint without using any privacy-sensitive IDs:

fingerprint = sha256(platform + "|" + model + "|" + install_id)

where install_id is persisted in secure storage on first run.

Lifecycle

stateDiagram-v2
    [*] --> Pending: Employee registers device
    Pending --> Approved: HR approves
    Pending --> Revoked: HR rejects
    Approved --> Revoked: HR revokes (loss/theft)
    Revoked --> [*]

Enforcement

• Unit setting device_binding = true gates punches.
• Pending / revoked devices → 423 DEVICE_NOT_APPROVED.
• When disabled globally, fingerprints are still recorded for audit but never block.

Multiple Devices

An employee can have multiple approved devices (work phone + personal phone). There's no cap; HR enforces policy out-of-band.

API

POST /api/v1/devices/register
{
  "fingerprint": "abc123",
  "platform": "android",
  "model": "Pixel 7",
  "os_version": "14"
}

POST /api/v1/devices/{id}/approve
POST /api/v1/devices/{id}/revoke

Telegram Accounts

Telegram is a separate binding (employee_telegram_links) with the same approval model — HR approves the chat ID before the bot accepts commands.