# Face Enrollment + Interview Verification (DeepFace ArcFace)

Registration enrolls a **live** face reference (encrypted at rest). Interview verify matches live webcam frames to that enrollment with ArcFace + anti-spoof liveness. Raw biometric images/templates are **never** returned in API responses.

## Flow

```
Registration: Register → Live Face Scan → Liveness → Save Face Reference → Complete
Interview:    Start → Live Face Scan → Liveness → Face Match → Allow Interview
Failure:      Face Mismatch → Block Interview → Retry
```

`POST /id-verification/verify` and `POST /face-verification/manual-review` are **disabled** (commented out).

## Endpoints

All require `X-Internal-Token`.

### 1. Enroll (registration)

`POST /api/v1/face-verification/enroll`

```json
{
  "user_id": "user-jane-001",
  "company_id": "co-acme-001",
  "live_frames_base64": ["<webcam 1>", "<webcam 2>", "<webcam 3>"],
  "consent_given": true,
  "consent_id": "consent-enroll-1"
}
```

- Prefer **≥2–3 live frames** (not a single static upload).
- Liveness must pass before the encrypted reference is stored.
- Response: `enrolled`, `enrollment_id`, `audit_id`, `enrolled_at` — no raw face bytes.

### 2. Verify (before interview)

`POST /api/v1/face-verification/verify`

```json
{
  "user_id": "user-jane-001",
  "interview_id": "int-face-1",
  "live_frames_base64": ["<webcam 1>", "<webcam 2>"],
  "consent_given": true,
  "consent_id": "consent-1"
}
```

| Field | Meaning |
|-------|---------|
| `reference_source` | `enrollment` or `none` |
| `identity.matched` | ArcFace: live ↔ enrolled reference |
| `liveness.passed` | Anti-spoof only |
| `verified` | consent ∧ identity ∧ liveness |

Do **not** start the interview until `verified=true`. Audits include status, timestamps, attempt counts, and image SHA-256 hashes only.

## Session gate

When `FACE_VERIFICATION_REQUIRED_FOR_SESSION=true` (default) or `require_face_verification=true` on session start, a recent **passed** audit for the same `interview_id` is required. Direct interview-start without verify returns `403 face_verification_required`.

## Pass criteria (verify)

1. `consent_given: true`
2. Active enrollment for `user_id`
3. DeepFace stack OK (`FACE_VALIDATE_DEPS`)
4. Live frames pass anti-spoof + presence + diversity gates
5. ArcFace match vs enrolled reference

## Setup

```bash
pip install deepface==0.0.102 opencv-python-headless tf-keras
```

Encrypted blobs use `FACE_ENROLLMENT_STORE_DIR` (default `.data/face_enrollment`) and the same Fernet key as `ID_VERIFICATION_ENCRYPTION_KEY` when set.

## Tests

```bash
pytest tests/test_face_verification.py tests/test_face_verification_deps_and_engine.py -q
```
