Authentica

Content authenticity & deepfake detection platform. Upload an image, audio, or video file and get back an explainable probability score indicating how likely the content is AI-generated or manipulated — with per-signal reasons and visual evidence, not just a number.

API-first (REST + API keys + async jobs + webhooks) with a light React dashboard for testing and key management. See plan.md for the full architecture and roadmap, and code.md for the running build log.

⚠️ Honest note: open deepfake detectors are imperfect and beatable. Authentica's value is the explainable, pluggable detection framework (swap/upgrade models freely; always know why a score was produced) — not any single model's raw accuracy.

---

Status

• ✅ Phase 0 — scaffolding (FastAPI + React, CI-ready).
• ✅ Phase 1 — pluggable detector engine + 4 forensic image detectors + sync POST /v1/scans + Analyze UI.
• ✅ Phase 2 — API keys, async jobs (/v1/jobs), signed webhooks, persistence (SQLite→Postgres), usage metering + Keys/Webhooks dashboard.
• ✅ ML classifier (optional) — pretrained AI-image detector wired as a pluggable detector (off by default).
• ✅ Audio (Phase 3) — async audio jobs: metadata/probe + spectral (bandwidth-cutoff/flatness) detectors with a spectrogram artifact. Needs ffmpeg (bundled via requirements-media.txt).
• ✅ Video (Phase 4) — async video jobs: frame sampling → image detectors per frame (averaged) + audio-track analysis + temporal consistency; evidence artifacts from the most-suspicious frame.

Optional: enable audio/video analysis (ffmpeg)

cd backend
./.venv/Scripts/python.exe -m pip install -r requirements-media.txt   # bundles a static ffmpeg

Then submit audio via the async jobs API (POST /v1/jobs with an audio/* file). Audio detection is heuristic-only for now (no ML model yet) — indicative, not proof.

Optional: enable the ML image classifier

The 4 forensic detectors run with no heavy deps. To also fuse in a pretrained deep-learning AI-image detector:

cd backend
./.venv/Scripts/python.exe -m pip install -r requirements-ml.txt   # torch + transformers
# enable it (first scan downloads the model to the HF cache):
AUTHENTICA_ENABLE_ML_IMAGE=true ./.venv/Scripts/python.exe -m uvicorn app.main:app --port 8077

The detector lazily loads and degrades gracefully — if the deps/model aren't present it is skipped without affecting the other detectors. Model is configurable via AUTHENTICA_ML_IMAGE_MODEL.

API quickstart

# 1) create an API key (admin-token gated; default dev token shown)
curl -X POST localhost:8077/v1/keys -H "X-Admin-Token: dev-admin-token" \
     -H "Content-Type: application/json" -d '{"name":"acme"}'
# -> { "id": "ak_...", "api_key": "ak_..._<secret>", ... }   (secret shown once)

# 2) submit an async analysis job
curl -X POST localhost:8077/v1/jobs -H "Authorization: Bearer <api_key>" -F "file=@photo.jpg"
# -> { "id": "<job_id>", "status": "queued" }

# 3) poll for the result
curl localhost:8077/v1/jobs/<job_id> -H "Authorization: Bearer <api_key>"

# 4) (optional) register a signed webhook to be notified on completion
curl -X POST localhost:8077/v1/webhooks -H "Authorization: Bearer <api_key>" \
     -H "Content-Type: application/json" \
     -d '{"url":"https://example.com/hook","events":"job.completed"}'
# deliveries are signed: header X-Authentica-Signature: sha256=<hmac over "{timestamp}.{body}">

Dev note: with Docker/Redis unavailable, persistence uses SQLite and async jobs run on an in-process thread pool (set AUTHENTICA_JOBS_EAGER=true to run them inline). Both sit behind clean interfaces so Postgres + arq/Redis drop in without API changes.

Tech stack

• Backend: FastAPI (Python 3.12), Pydantic v2. Pluggable detector registry + score fusion.
• Frontend: Vite + React + TypeScript.
• Storage/DB (dev): SQLite + local disk by default — no external services required to run. Swappable to Postgres / Redis / S3 (MinIO) for production.

Prerequisites

• Python 3.11+ and Node 18+ (developed on Python 3.12.4 / Node 24).
• ffmpeg is required only for the audio/video phases (Phases 3–4).

Run it locally

Backend (port 8077)

cd backend
python -m venv .venv
./.venv/Scripts/python.exe -m pip install -r requirements.txt    # Windows
# source .venv/bin/activate && pip install -r requirements.txt   # macOS/Linux
./.venv/Scripts/python.exe -m uvicorn app.main:app --reload --port 8077

• Health: http://localhost:8077/healthz
• Interactive API docs (OpenAPI): http://localhost:8077/docs

Frontend (port 5173)

cd frontend
npm install
npm run dev

Open http://localhost:5173 — the page calls the backend /healthz (proxied via Vite) and shows status.

Tests & lint

# backend
cd backend && ./.venv/Scripts/python.exe -m pytest && ./.venv/Scripts/python.exe -m ruff check .
# frontend
cd frontend && npm run build      # runs tsc --noEmit then a production build

Configuration

Backend config is via env vars prefixed AUTHENTICA_ (or a backend/.env file). See backend/.env.example. Defaults run with zero external services.

Project layout

authentica/
  plan.md        # approved architecture + phased roadmap
  code.md        # running build/change log (read this to resume work)
  backend/       # FastAPI app, detectors, services, tests
  frontend/      # Vite + React + TS dashboard