# Facial attendance deployment gate

For the full architecture, implementation history, operational flows, security
controls, troubleshooting guide, and acceptance checklist, see
[`FACIAL_ATTENDANCE_IMPLEMENTATION.md`](FACIAL_ATTENDANCE_IMPLEMENTATION.md).

Facial attendance is disabled by default. Do not enable it in production until
the organization's Data Protection Officer (DPO) has approved the Privacy
Impact Assessment (PIA), lawful-basis reference, employee notice, fallback, and
retention schedule.

## Technical setup

1. Run `php backend/scripts/install_facial_attendance.php` on the target server
   This applies both facial-attendance migrations idempotently.
   Before migrating, `php backend/scripts/check_facial_attendance_prerequisites.php`
   can verify that the target already has the required modern attendance schema.
2. Copy `backend/server/privacy_config.example.php` to
   `backend/server/privacy_config.local.php` and replace the sample with at
   least 32 cryptographically random bytes. Production may instead define the
   `FACIAL_ATTENDANCE_ENCRYPTION_KEY` environment variable.
3. Serve the site over HTTPS. Camera access is intentionally restricted to the
   application's own origin.
4. Schedule `php backend/scripts/purge_facial_attendance_data.php` daily.
5. In Settings → Facial Attendance, select the brand and enter the DPO-approved
   notice version/text, lawful-basis reference, PIA reference, DPO contact,
   fallback, and retention periods. Enabling also requires an explicit approval
   attestation, which is written to the audit log. Only then enable the feature.
6. Enroll employees in person under administrator supervision. The employee
   must be shown the notice and fallback before acknowledgment is recorded.
7. On the intended kiosk, sign in as an authorized admin, activate that browser
   for one branch, then log out into kiosk mode.
8. Leave **Face-only kiosk identification (1:N)** off unless the approved PIA,
   notice, necessity/proportionality assessment, and employee communication
   explicitly cover identification against the enrolled population. Save the
   policy again with the approval attestation when turning it on.

## Privacy and security behavior

- Raw camera frames are processed locally and are not uploaded or stored.
- Only an AES-256-GCM encrypted numerical template is stored at rest.
- Verification uses a one-use, two-minute challenge and server-side comparison.
- Face-only identification is opt-in, searches only the authorized device's
  assigned branch, is capped at 500 active templates, and rejects a result when
  the best and second-best candidates are too close. It never returns candidate
  identities on a rejected scan.
- Kiosk credentials are random, `HttpOnly`, branch-scoped, expiring, audited,
  and remotely revocable. Production cross-origin deployments require HTTPS and
  use `Secure; SameSite=None`; same-origin deployments use `SameSite=Strict`.
- Attendance timestamps are generated by the PHP server in `Asia/Manila`.
- Revocation erases template ciphertext immediately. The scheduled retention job
  erases expired template ciphertext and deletes expired verification events.
- A documented non-biometric fallback is always displayed at the kiosk.

## Required organizational work

Technical controls alone do not establish legal compliance. Before rollout,
the DPO should document necessity and proportionality, validate the applicable
lawful basis, consult employees where required, test false accepts/rejects and
demographic performance, establish access-review and incident-response
procedures, train authorized administrators, and approve the retention and
data-subject request process.

The built-in browser liveness checks are an MVP control, not a certification.
For higher-risk deployments, the PIA should assess whether a vetted server-side
or on-premises liveness provider is necessary. Any external provider requires a
processor agreement and cross-border/data-transfer review before integration.

Face-only 1:N identification creates greater privacy and false-identification
risk than 1:1 employee-ID verification. Pilot it with representative employees,
measure false accepts/rejects, keep the documented fallback immediately
available, and have the DPO/legal team approve the actual production context.