SelfieAuth (OpenCV)

About

Local face-recognition demo for enrollment and authentication. It is split into two parts:

• SDK (Python): does the heavy lifting (OpenCV + storage + REST API)
• Client (JS): pluggable UI that talks to the API

Architecture

The API runs separately from the UI. A web app embeds the JS client (or the sample UI) and points it at the API base URL. The browser captures a selfie, sends it to the API, and receives a decision.

The API

Endpoints:

• POST /signup enroll a person and retrain (name + email required)
• POST /signup-frame enroll from client images
• POST /authenticate authenticate once from camera
• POST /authenticate-frame authenticate from a client-captured image
• POST /detect-frame detect faces in a client-captured image
• POST /deletefaces clear all known faces, models, snapshots, and logs

Swagger UI: http://127.0.0.1:8000/apidocs

The Pluggable JS App

The client uses window.FaceVerifyConfig for simple branding and text changes.

<script>
  window.FaceVerifyConfig = {
    brand: "Acme Verify",
    title: "Confirm your identity in seconds.",
    authLabel: "Authenticate",
    colors: { accent: "#0f6f4f" }
  };
</script>
<!-- Use your hosted build of the client from `client/face-auth-client.js` (or `client/dist/face-auth-client.js` if you build one) -->
<script src="https://your-cdn.example.com/face-auth-client.js"></script>
<script>
  const client = new FaceAuthClient({
    baseUrl: "http://127.0.0.1:8000",
    video: document.querySelector("video")
  });
  await client.startCamera();
  const result = await client.authenticate();
  console.log(result);
</script>

Development

Prereqs: Python 3.10+, webcam, OpenCV system deps.

Install:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Run locally (no Docker)

Start API:

python app.py serve --cors "http://127.0.0.1:5500"

Start UI:

python -m http.server 5500 -d client

Then open:

• UI: http://127.0.0.1:5500
• Swagger: http://127.0.0.1:8000/apidocs

Stop:

• API: Ctrl+C
• UI server: Ctrl+C

Docker

Run with Docker Compose

Bring up the API and UI together:

docker-compose up --build

Then open:

• UI: http://127.0.0.1:5500
• Swagger: http://127.0.0.1:8000/apidocs

Notes:

• The UI defaults to http://127.0.0.1:8000 for the API. You can override with ?api=http://127.0.0.1:8000.
• The Compose file already maps /dev/video0 for Linux webcam access.