Skip to content

About

FastAPI Python Deepfake Facial and OpenCV Liveness detection API with JWT token authentication and token-bucket rate limiting.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Name-that-face πŸ”

License: MIT

Deepfake detection as a service with dual liveness detection, strict government ID validation, and face matching. The flow:

  1. 2FA: Duo push authentication (step-up for sensitive operations)
  2. Liveness Detection: Dual-layered anti-spoofing
    • Sensor-based: Gyroscope + accelerometer verify real device motion
    • Video-based: Frame analysis detects natural movement patterns
  3. Government ID Validation: OCR + face detection + keyword verification
  4. Face Matching: DeepFace (ArcFace) ensures selfie matches ID
  5. Rate Limiting: Token-bucket limiter prevents abuse
  6. Audit Logging: Append-only JSON log for compliance

Requirements

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

Project structure

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)

Local development setup

1. Install Tesseract OCR (system dependency)

macOS:

brew install tesseract

Ubuntu/Debian:

apt-get update && apt-get install -y tesseract-ocr

Windows: Download installer from https://github.com/UB-Mannheim/tesseract/wiki

Verify: tesseract --version

2. Configure environment

Server (.env):

cp .env.example .env
# Fill in: DUO_INTEGRATION_KEY, DUO_SECRET_KEY, DUO_API_HOST, SECRET_KEY

Client (.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 testing

3. Install Python dependencies

poetry install
poetry run python --version   # Python 3.12.x

4. Set up the DeepFace venv (one-time, ~5 min)

DeepFace + 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.

5. Install pre-commit hooks

poetry run python -m pre_commit install --hook-type pre-commit --hook-type pre-push

Task runner β€” inv

All developer workflows go through Invoke.

poetry run inv --list   # show all available tasks

Servers

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

ngrok

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

Token generation

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.

Testing

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 --unit and --integration flags.

Linting & formatting

Command What it does
poetry run inv lint ruff check src/ tests/
poetry run inv fmt ruff format src/ tests/

Pre-commit hooks

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-push

Skip in an emergency:

git commit --no-verify
git push --no-verify

Swagger UI

Interactive docs: http://localhost:8000/docs

  1. poetry run inv token β€” copy the JWT
  2. Click Authorize πŸ”’ (top-right)
  3. Paste the token β†’ Authorize β†’ try any endpoint from the browser

ngrok setup (mobile / public access)

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 URL

Open the public URL on your phone to run the full Duo push β†’ selfie β†’ gov ID flow.


Docker deployment

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

Environment variables

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

Duo Security setup

  1. Log in to https://admin.duosecurity.com
  2. Applications β†’ Protect an Application β†’ Auth API β†’ Protect
  3. Copy Integration key, Secret key, API hostname into .env
  4. Under Users, add a user matching USERNAME in src/client.py (default: me@lorenamesa.com) and enroll a device

Liveness Detection Flow

The Streamlit client enforces a multi-step verification:

  1. 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
  2. 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)
  3. Selfie Capture (only if liveness passes)

    • Camera photo of user's face
  4. 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
  5. DeepFace Verification (only if ID valid)

    • Compares selfie against government ID
    • Returns confidence score and match distance

API Reference

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

Audit log

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 user

Logging

Structured 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

About

FastAPI Python Deepfake Facial and OpenCV Liveness detection API with JWT token authentication and token-bucket rate limiting.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages