Deepfake detection as a service with dual liveness detection, strict government ID validation, and face matching. The flow:
- 2FA: Duo push authentication (step-up for sensitive operations)
- Liveness Detection: Dual-layered anti-spoofing
- Sensor-based: Gyroscope + accelerometer verify real device motion
- Video-based: Frame analysis detects natural movement patterns
- Government ID Validation: OCR + face detection + keyword verification
- Face Matching: DeepFace (ArcFace) ensures selfie matches ID
- Rate Limiting: Token-bucket limiter prevents abuse
- Audit Logging: Append-only JSON log for compliance
| Tool | Version | Notes |
|---|---|---|
| Python | 3.12 | Main app and deepface venv |
| Poetry | β₯ 2.0 | Dependency management |
| Tesseract OCR | β₯ 5 | Document validation (system-level dependency) |
| Docker + Docker Compose | β₯ 27 | Containerised deployment |
| ngrok | β₯ 3 | Expose local ports over HTTPS |
| Duo account | any | Free trial works; needs Auth API application |
name-that-face/
βββ src/
β βββ app.py # FastAPI routes + Swagger config
β βββ client.py # Streamlit front-end
β βββ dependencies.py # Singleton wiring (settings, duo, services)
β βββ document_validator.py # OCR + face detection for government IDs
β βββ fraud_detection_service.py # DeepFace wrapper (subprocess)
β βββ liveness_detector.py # OpenCV-based video liveness analysis
β βββ sensor_bridge.py # JavaScript bridge for motion sensors
β βββ logging_config.py # structlog (pretty dev / JSON prod)
β βββ models.py # Pydantic request/response models
β βββ rate_limiter.py # Token-bucket rate limiter + @rate_limit
β βββ settings.py # Pydantic settings (env vars / .env)
β βββ token_service.py # JWT issue / validate / refresh + TokenError
βββ tests/
β βββ conftest.py # Shared JWT fixtures
β βββ unit/ # @pytest.mark.unit β fast, no I/O (~0.7s)
β β βββ test_token_bucket.py
β β βββ test_token_service.py
β β βββ test_fraud_detection.py
β β βββ test_models.py
β β βββ test_settings.py
β βββ integration/ # @pytest.mark.integration β full FastAPI
β βββ test_api_auth.py
β βββ test_api_2fa.py
β βββ test_api_photo.py
βββ config/config.yml # Token types, scopes, rate-limit config
βββ scripts/validate_2fa_flow.py # Manual end-to-end 2FA script
βββ tasks.py # Invoke task runner (inv serve, inv test β¦)
βββ token_task.py # Logic for inv token
βββ pyproject.toml # Poetry + pytest + ruff config
βββ .pre-commit-config.yaml # Pre-commit hooks (ruff + tests)
βββ deepface-requirements.txt # Pinned deps for the isolated deepface venv
βββ Dockerfile / Dockerfile.client # Multi-stage API + Streamlit containers
βββ docker-compose.yml # Wires api + client services
βββ .env.example # Safe template for server β copy to .env
βββ .env.client.example # Safe template for client β copy to .env.client
βββ logs/audit_log.jsonl # Append-only audit log (auto-created)
macOS:
brew install tesseractUbuntu/Debian:
apt-get update && apt-get install -y tesseract-ocrWindows: Download installer from https://github.com/UB-Mannheim/tesseract/wiki
Verify: tesseract --version
Server (.env):
cp .env.example .env
# Fill in: DUO_INTEGRATION_KEY, DUO_SECRET_KEY, DUO_API_HOST, SECRET_KEYClient (.env.client):
cp .env.client.example .env.client
# Fill in: API_BASE_URL (default: http://127.0.0.1:8000)
# Other defaults work for local testingpoetry install
poetry run python --version # Python 3.12.xDeepFace + TensorFlow run in a separate Python 3.12 venv β TensorFlow is incompatible with Python 3.13 and too heavy to run in the main process.
python3.12 -m venv /Users/lorenamesa/Workspace/deepface-venv
source /Users/lorenamesa/Workspace/deepface-venv/bin/activate
pip install -r deepface-requirements.txt
deactivate
# Verify
/Users/lorenamesa/Workspace/deepface-venv/bin/python \
-c "from deepface import DeepFace; print('DeepFace OK')"First request: ArcFace model weights (~600 MB) download to
~/.deepface/weights/on first use.
poetry run python -m pre_commit install --hook-type pre-commit --hook-type pre-pushAll developer workflows go through Invoke.
poetry run inv --list # show all available tasks| Command | What it does |
|---|---|
poetry run inv serve |
FastAPI on http://127.0.0.1:8000 (hot-reload) |
poetry run inv client |
Streamlit UI on http://localhost:8501 |
| Command | What it does |
|---|---|
poetry run inv ngrok |
Tunnel Streamlit (:8501) to a public HTTPS URL |
poetry run inv ngrok --port 8000 |
Tunnel the API instead |
poetry run inv ngrok --url |
Print the current public ngrok URL |
Generate signed JWTs for curl testing and Swagger UI authorization.
| Command | Scope | Notes |
|---|---|---|
poetry run inv token |
user:read |
Default β 30 min TTL |
poetry run inv token --scope user:write --step-up |
user:write |
step_up=True required for write endpoints |
poetry run inv token --scope admin:admin --step-up |
admin:admin |
Full admin access |
poetry run inv token --ttl 120 |
user:read |
Custom TTL in minutes |
poetry run inv token --user-id alice --username alice@example.com |
user:read |
Custom identity |
poetry run inv token --list-scopes |
β | Print all 17 valid scopes from config.yml |
Every call prints a summary table, the raw JWT, and a ready-to-paste curl example.
| Command | What it does |
|---|---|
poetry run inv test |
All tests (run separately: unit then integration) |
poetry run inv test --unit |
64 unit tests (~0.7s, no I/O) |
poetry run inv test --integration |
16 integration tests + 2 skipped (full FastAPI) |
poetry run inv test --coverage |
All tests + HTML report in htmlcov/ |
poetry run inv test --verbose |
Any of the above with -v |
Note: Unit and integration tests should be run separately due to pytest singleton isolation. CI runs them with
--unitand--integrationflags.
| Command | What it does |
|---|---|
poetry run inv lint |
ruff check src/ tests/ |
poetry run inv fmt |
ruff format src/ tests/ |
Installed into .git/hooks/ β run automatically on git commit and git push.
| Hook | Trigger | What it does |
|---|---|---|
ruff |
commit | Lint + auto-fix |
ruff-format |
commit | Auto-format |
unit tests |
commit | 49 unit tests (-m unit) |
integration tests |
push | 18 integration tests (-m integration) |
If ruff modifies files, stage them and re-commit. Tests must pass before commit/push completes.
Re-install after cloning:
poetry install
poetry run python -m pre_commit install --hook-type pre-commit --hook-type pre-pushSkip in an emergency:
git commit --no-verify
git push --no-verifyInteractive docs: http://localhost:8000/docs
poetry run inv tokenβ copy the JWT- Click Authorize π (top-right)
- Paste the token β Authorize β try any endpoint from the browser
brew install ngrok
ngrok config add-authtoken <YOUR_AUTHTOKEN> # one-time setup
poetry run inv ngrok # start tunnel on :8501
poetry run inv ngrok --url # print the URLOpen the public URL on your phone to run the full Duo push β selfie β gov ID flow.
docker compose up --build # first run (~10 min β TensorFlow layer)
docker compose up # subsequent runs
docker compose down # stop
docker compose logs -f api # tail JSON logs| Service | Port | Description |
|---|---|---|
api |
8000 | FastAPI β rate limiter, Duo 2FA, DeepFace |
client |
8501 | Streamlit front-end |
| Variable | Required | Default | Description |
|---|---|---|---|
DUO_INTEGRATION_KEY |
β | β | Duo Auth API integration key |
DUO_SECRET_KEY |
β | β | Duo Auth API secret key |
DUO_API_HOST |
β | β | e.g. api-xxxxxxxx.duosecurity.com |
SECRET_KEY |
β | insecure default | JWT signing secret |
ACCESS_TOKEN_EXPIRE_MINUTES |
30 |
JWT TTL | |
DEEPFACE_PYTHON |
/opt/deepface-venv/bin/python |
Set automatically in Docker | |
AUDIT_LOG_PATH |
/app/logs/audit_log.jsonl |
Set automatically in Docker | |
LOG_FORMAT |
pretty / json in Docker |
pretty or json |
|
LOG_LEVEL |
INFO |
DEBUG, INFO, WARNING, ERROR |
|
API_BASE_URL |
http://api:8000 |
URL the Streamlit client calls |
Client configuration (Streamlit):
| Variable | Default | Description |
|---|---|---|
API_BASE_URL |
http://api:8000 |
Backend API URL |
JWT_SECRET |
test-secret-change-me |
Must match server SECRET_KEY |
USER_ID |
test-user-1 |
Test user ID |
USERNAME |
test@example.com |
Test username for JWT |
USER_NAME |
Test User |
Display name in payload |
USER_EMAIL |
test@example.com |
Email in payload |
USER_AGE |
25 |
Age in payload |
CLIENT_LOG_PATH |
/tmp/name_that_face_client.log |
Client logging file |
- Log in to https://admin.duosecurity.com
- Applications β Protect an Application β Auth API β Protect
- Copy Integration key, Secret key, API hostname into
.env - Under Users, add a user matching
USERNAMEinsrc/client.py(default:me@lorenamesa.com) and enroll a device
The Streamlit client enforces a multi-step verification:
-
Motion Sensor Capture (5 seconds)
- Captures gyroscope + accelerometer data
- Captures video frames via camera (optional WebRTC future enhancement)
- JavaScript analyzes locally for natural movement patterns
-
Liveness Pass/Fail
- Requires both sensor motion AND video consistency
- Prevents deepfakes (can't fake gyro + video sync)
- Prevents printed photos (can't move with sensors)
-
Selfie Capture (only if liveness passes)
- Camera photo of user's face
-
Government ID Upload (only if selfie captured)
- OCR validation: must contain ID keywords + dates
- Face detection: must have visible face
- Text validation: checks for government ID fields
-
DeepFace Verification (only if ID valid)
- Compares selfie against government ID
- Returns confidence score and match distance
Interactive docs: http://localhost:8000/docs
| Method | Path | Scope | Description |
|---|---|---|---|
GET |
/api/user/{user_id} |
user:read |
Get user info from JWT claims |
POST |
/api/user/{user_id} |
user:write + step_up |
Update user β 307 to 2FA if not elevated |
POST |
/login-2fa |
challenge token | Complete Duo push; returns elevated JWT |
POST |
/api/user/{user_id}/photo |
user:write + step_up |
Selfie + gov ID β DeepFace result + audit log |
POST |
/api/liveness/frames |
user:write |
Upload video frames for server-side OpenCV analysis (future) |
POST |
/api/liveness/analyze |
user:write |
Analyze frames with OpenCV for liveness confidence |
POST |
/api/fraud/detect |
admin:admin + step_up |
Raw fraud detection on image/video/base64 |
Every /photo call appends one JSON line to logs/audit_log.jsonl:
{"user_id":"1","selfie_hash":"52a9f0...","gov_id_hash":"aadc83...","verified":true,"confidence":0.555,"analyzed_at":"2026-08-10T19:34:55+00:00"}cat logs/audit_log.jsonl | jq 'select(.verified == false)' # failures
cat logs/audit_log.jsonl | jq 'select(.user_id == "1")' # by userStructured logs via structlog.
Development (LOG_FORMAT=pretty):
2026-08-10T19:43:29Z [info] audit_log.written [app] user_id=1 verified=True confidence=0.555
Production / Docker (LOG_FORMAT=json):
{"user_id":"1","verified":true,"event":"audit_log.written","level":"info","logger":"app","timestamp":"2026-08-10T19:43:29Z"}Override at runtime: LOG_LEVEL=DEBUG poetry run inv serve