django-camera-kit 0.1.0__py3-none-any.whl

django_camera_kit/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

django_camera_kit/apps.py

@@ -0,0 +1,7 @@
+from django.apps import AppConfig
+
+
+class DjangoCameraKitConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "django_camera_kit"
+    verbose_name = "Camera Kit"

django_camera_kit/kyc/apps.py

@@ -0,0 +1,8 @@
+from django.apps import AppConfig
+
+
+class DjangoCameraKitKycConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "django_camera_kit.kyc"
+    label = "camera_kit_kyc"
+    verbose_name = "Camera Kit — KYC"

django_camera_kit/kyc/conf.py

@@ -0,0 +1,24 @@
+from django.conf import settings
+
+DEFAULTS = {
+    # insightface model pack — see embeddings.py. Changing this to a model
+    # with a different embedding size requires a migration (see models.py).
+    "EMBEDDING_MODEL": "buffalo_sc",
+    # Cosine similarity threshold above which a selfie/ID pair is considered
+    # a match. This default is a starting point, not a calibrated value —
+    # tune it against real data before relying on it in production.
+    "MATCH_THRESHOLD": 0.45,
+    # Max requests per authenticated user against KYCVerifyView. Each request
+    # runs a full face-embedding inference pass — without a limit the
+    # endpoint is a cheap DoS/probing vector. DRF throttle-rate syntax
+    # ("N/period" — second/minute/hour/day).
+    "THROTTLE_RATE": "10/hour",
+    # Reject selfie/id_document uploads larger than this, before they're
+    # saved or processed.
+    "MAX_UPLOAD_SIZE_MB": 8,
+}
+
+
+def get_setting(name):
+    user_settings = getattr(settings, "DJANGO_CAMERA_KIT_KYC", {})
+    return user_settings.get(name, DEFAULTS[name])

django_camera_kit/kyc/embeddings.py

@@ -0,0 +1,39 @@
+import numpy as np
+
+from . import conf
+
+_face_app = None
+
+
+def _get_face_app():
+    global _face_app
+    if _face_app is None:
+        from insightface.app import FaceAnalysis
+
+        _face_app = FaceAnalysis(
+            name=conf.get_setting("EMBEDDING_MODEL"),
+            providers=["CPUExecutionProvider"],
+        )
+        _face_app.prepare(ctx_id=-1, det_size=(320, 320))
+    return _face_app
+
+
+def extract_face_embedding(image_bgr):
+    """Return the normalized embedding of the largest face in the image,
+    or None if no face was detected — also if `image_bgr` is None, which
+    is what cv2.imdecode() returns for corrupt/malformed image data that
+    nonetheless passed DRF's ImageField validation."""
+    if image_bgr is None:
+        return None
+    faces = _get_face_app().get(image_bgr)
+    if not faces:
+        return None
+    largest = max(
+        faces, key=lambda f: (f.bbox[2] - f.bbox[0]) * (f.bbox[3] - f.bbox[1])
+    )
+    return largest.normed_embedding
+
+
+def compare_embeddings(embedding_a, embedding_b):
+    """Cosine similarity between two normalized embeddings, in [-1, 1]."""
+    return float(np.dot(embedding_a, embedding_b))

django_camera_kit/kyc/migrations/0001_initial.py

@@ -0,0 +1,85 @@
+# Generated by Django 5.0.14 on 2026-07-10 10:22
+
+import django.db.models.deletion
+import pgvector.django.indexes
+import pgvector.django.vector
+from django.conf import settings
+from django.db import migrations, models
+from pgvector.django import VectorExtension
+
+
+class Migration(migrations.Migration):
+    initial = True
+
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        VectorExtension(),
+        migrations.CreateModel(
+            name="KYCVerification",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                ("selfie", models.ImageField(upload_to="camera_kit/kyc/selfies/")),
+                (
+                    "id_document",
+                    models.ImageField(upload_to="camera_kit/kyc/id_documents/"),
+                ),
+                (
+                    "selfie_embedding",
+                    pgvector.django.vector.VectorField(
+                        blank=True, dimensions=512, null=True
+                    ),
+                ),
+                (
+                    "id_face_embedding",
+                    pgvector.django.vector.VectorField(
+                        blank=True, dimensions=512, null=True
+                    ),
+                ),
+                ("match_score", models.FloatField(blank=True, null=True)),
+                ("liveness_passed", models.BooleanField(default=False)),
+                (
+                    "status",
+                    models.CharField(
+                        choices=[
+                            ("pending", "En attente"),
+                            ("verified", "Vérifié"),
+                            ("rejected", "Rejeté"),
+                        ],
+                        default="pending",
+                        max_length=16,
+                    ),
+                ),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                (
+                    "user",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="kyc_verifications",
+                        to=settings.AUTH_USER_MODEL,
+                    ),
+                ),
+            ],
+            options={
+                "indexes": [
+                    pgvector.django.indexes.HnswIndex(
+                        ef_construction=64,
+                        fields=["selfie_embedding"],
+                        m=16,
+                        name="camera_kit_kyc_selfie_hnsw",
+                        opclasses=["vector_cosine_ops"],
+                    )
+                ],
+            },
+        ),
+    ]

django_camera_kit/kyc/models.py

@@ -0,0 +1,67 @@
+from django.conf import settings
+from django.db import models
+from pgvector.django import HnswIndex, VectorField
+
+# Matches buffalo_sc's w600k_mbf recognition output (see embeddings.py).
+# Changing the embedding model to one with a different output size requires
+# a new migration.
+EMBEDDING_DIMENSIONS = 512
+
+
+class KYCVerification(models.Model):
+    class Status(models.TextChoices):
+        PENDING = "pending", "En attente"
+        VERIFIED = "verified", "Vérifié"
+        REJECTED = "rejected", "Rejeté"
+
+    # Every verification is bound to the authenticated user who submitted
+    # it (KYCVerifyView requires authentication) — a verification result
+    # is meaningless without knowing whose identity it claims to confirm.
+    user = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.CASCADE,
+        related_name="kyc_verifications",
+    )
+
+    # selfie/id_document contain biometric + government-ID imagery. The
+    # consuming project MUST point Django's storage backend at a private,
+    # access-controlled location for these — never a publicly readable
+    # MEDIA_URL. django-camera-kit doesn't enforce this itself since
+    # storage config is the consuming project's responsibility, but the
+    # API response (KYCVerificationSerializer) deliberately never exposes
+    # these files' URLs.
+    selfie = models.ImageField(upload_to="camera_kit/kyc/selfies/")
+    id_document = models.ImageField(upload_to="camera_kit/kyc/id_documents/")
+
+    selfie_embedding = VectorField(
+        dimensions=EMBEDDING_DIMENSIONS, null=True, blank=True
+    )
+    id_face_embedding = VectorField(
+        dimensions=EMBEDDING_DIMENSIONS, null=True, blank=True
+    )
+    match_score = models.FloatField(null=True, blank=True)
+
+    # MVP liveness only: client-asserted result of the in-browser
+    # head-movement challenge. Not a server-verified anti-spoofing signal —
+    # a malicious client could send True without ever performing it. Real
+    # server-side liveness verification is a later phase.
+    liveness_passed = models.BooleanField(default=False)
+
+    status = models.CharField(
+        max_length=16, choices=Status.choices, default=Status.PENDING
+    )
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    class Meta:
+        indexes = [
+            HnswIndex(
+                name="camera_kit_kyc_selfie_hnsw",
+                fields=["selfie_embedding"],
+                m=16,
+                ef_construction=64,
+                opclasses=["vector_cosine_ops"],
+            ),
+        ]
+
+    def __str__(self):
+        return f"KYCVerification #{self.pk} ({self.status})"

django_camera_kit/kyc/serializers.py

@@ -0,0 +1,23 @@
+from rest_framework import serializers
+
+from . import conf
+from .models import KYCVerification
+
+
+def validate_upload_size(file):
+    max_mb = conf.get_setting("MAX_UPLOAD_SIZE_MB")
+    if file.size > max_mb * 1024 * 1024:
+        raise serializers.ValidationError(f"Fichier trop volumineux (max {max_mb} Mo).")
+
+
+class KYCSubmissionSerializer(serializers.Serializer):
+    selfie = serializers.ImageField(validators=[validate_upload_size])
+    id_document = serializers.ImageField(validators=[validate_upload_size])
+    liveness_passed = serializers.BooleanField(default=False)
+
+
+class KYCVerificationSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = KYCVerification
+        fields = ["id", "status", "match_score", "liveness_passed", "created_at"]
+        read_only_fields = fields

django_camera_kit/kyc/static/django_camera_kit/kyc/css/kyc_capture.css

@@ -0,0 +1,59 @@
+.camera-kit-kyc {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  flex-wrap: wrap;
+}
+
+/* ISO/IEC 7810 ID-1 format (85.60 x 53.98mm) — the size of virtually every
+   national ID card, driving license and payment card. The ratio is fixed
+   via aspect-ratio so it holds regardless of the camera's own aspect
+   ratio, instead of an arbitrary box that doesn't match a real card. */
+.camera-kit-kyc-id-guide {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: 75%;
+  aspect-ratio: 85.6 / 53.98;
+  transform: translate(-50%, -50%);
+  border: 3px dashed rgba(255, 255, 255, 0.8);
+  border-radius: 0.5rem;
+  pointer-events: none;
+}
+
+.camera-kit-kyc-face-guide {
+  position: absolute;
+  top: 12%;
+  left: 30%;
+  right: 30%;
+  bottom: 12%;
+  border: 3px dashed rgba(255, 255, 255, 0.8);
+  border-radius: 50%;
+  pointer-events: none;
+}
+
+.camera-kit-kyc-hint {
+  text-align: center;
+  padding: 0.5rem 1rem;
+  margin: 0;
+  font-weight: 600;
+}
+
+.camera-kit-kyc-review {
+  display: flex;
+  gap: 1rem;
+  padding: 1rem;
+  justify-content: center;
+}
+
+.camera-kit-kyc-review img {
+  max-height: 180px;
+  border-radius: 0.25rem;
+  border: 1px solid #dee2e6;
+}
+
+.camera-kit-kyc-review-status,
+.camera-kit-kyc-result {
+  text-align: center;
+  padding: 0 1rem;
+}

django_camera_kit/kyc/static/django_camera_kit/kyc/js/face_kit.js

@@ -0,0 +1,116 @@
+(function (window, document) {
+  "use strict";
+
+  // Locate vendor/ relative to this script's own URL so it works under any
+  // STATIC_URL prefix, instead of hardcoding a path.
+  var scriptUrl = document.currentScript && document.currentScript.src;
+  var vendorBase = scriptUrl ? scriptUrl.replace(/js\/face_kit\.js.*$/, "vendor/") : "";
+  var MODEL_FILE = "face_detection_yunet_2023mar.onnx";
+
+  var detector = null;
+  var readyPromise = null;
+
+  function loadModelFile(cv) {
+    return fetch(vendorBase + MODEL_FILE)
+      .then(function (r) {
+        return r.arrayBuffer();
+      })
+      .then(function (buf) {
+        cv.FS_createDataFile("/", MODEL_FILE, new Uint8Array(buf), true, false, false);
+      });
+  }
+
+  // Reuses the opencv.js instance already loaded by CameraKit (camera_kit.js
+  // must run before this file) instead of vendoring a second CV stack.
+  //
+  // Uses YuNet (cv.FaceDetectorYN), a small CNN trained on WIDER FACE —
+  // deliberately not a Haar cascade. Haar cascades detect faces from
+  // brightness-contrast patterns and are well documented to have far
+  // higher miss rates on darker skin tones and low-contrast lighting
+  // (see e.g. Buolamwini & Gebru, "Gender Shades", 2018). YuNet doesn't
+  // carry that specific bias.
+  function ready() {
+    if (readyPromise) return readyPromise;
+
+    readyPromise = window.CameraKit.ready().then(function (cvIsReady) {
+      if (!cvIsReady) return false;
+      var cv = window.CameraKit.getCv();
+      if (!cv.FaceDetectorYN) return false;
+
+      return loadModelFile(cv).then(function () {
+        // This embind binding exposes the C++ static FaceDetectorYN::create()
+        // factory as a plain constructor, not a .create() static method.
+        detector = new cv.FaceDetectorYN(
+          MODEL_FILE,
+          "",
+          new cv.Size(320, 320),
+          0.8,
+          0.3,
+          5000,
+          0,
+          0
+        );
+        return true;
+      });
+    });
+
+    return readyPromise;
+  }
+
+  // Largest detected face as {x, y, width, height, centerX, centerY, score}
+  // in canvas pixel coordinates, or null if none found.
+  function detectFace(canvas) {
+    var cv = window.CameraKit.getCv();
+    if (!cv || !detector) return null;
+
+    detector.setInputSize(new cv.Size(canvas.width, canvas.height));
+
+    var src = cv.imread(canvas);
+    var bgr = new cv.Mat();
+    var faces = new cv.Mat();
+    var result = null;
+
+    try {
+      cv.cvtColor(src, bgr, cv.COLOR_RGBA2BGR);
+      detector.detect(bgr, faces);
+
+      if (faces.rows > 0) {
+        var bestRow = 0;
+        var bestArea = 0;
+        for (var i = 0; i < faces.rows; i++) {
+          var area = faces.floatAt(i, 2) * faces.floatAt(i, 3);
+          if (area > bestArea) {
+            bestArea = area;
+            bestRow = i;
+          }
+        }
+
+        var x = faces.floatAt(bestRow, 0);
+        var y = faces.floatAt(bestRow, 1);
+        var width = faces.floatAt(bestRow, 2);
+        var height = faces.floatAt(bestRow, 3);
+
+        result = {
+          x: x,
+          y: y,
+          width: width,
+          height: height,
+          centerX: x + width / 2,
+          centerY: y + height / 2,
+          score: faces.floatAt(bestRow, 14),
+        };
+      }
+    } finally {
+      src.delete();
+      bgr.delete();
+      faces.delete();
+    }
+
+    return result;
+  }
+
+  window.FaceKit = {
+    ready: ready,
+    detectFace: detectFace,
+  };
+})(window, document);