django-camera-kit 0.1.0__tar.gz

django_camera_kit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AltiusAO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

django_camera_kit-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+recursive-include django_camera_kit/static *
+recursive-include django_camera_kit/templates *
+recursive-include django_camera_kit/kyc/static *
+recursive-include django_camera_kit/kyc/templates *

django_camera_kit-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: django-camera-kit
+Version: 0.1.0
+Summary: Document scanning and KYC face verification widgets for Django
+Author: Altius Academy SNC
+Author-email: Paul Guindo <paulguindo@altius-group.ch>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Altius-Academy-SNC/django-camera-kit
+Project-URL: Documentation, https://altius-academy-snc.github.io/django-camera-kit
+Project-URL: Repository, https://github.com/Altius-Academy-SNC/django-camera-kit
+Project-URL: Issues, https://github.com/Altius-Academy-SNC/django-camera-kit/issues
+Keywords: django,camera,document-scanner,kyc,identity-verification
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 6.0
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Multimedia :: Graphics :: Capture
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: django>=4.2
+Provides-Extra: kyc
+Requires-Dist: djangorestframework>=3.14; extra == "kyc"
+Requires-Dist: pgvector>=0.2; extra == "kyc"
+Requires-Dist: psycopg[binary]>=3.1; extra == "kyc"
+Requires-Dist: insightface>=0.7; extra == "kyc"
+Requires-Dist: onnxruntime>=1.16; extra == "kyc"
+Requires-Dist: pillow>=10.0; extra == "kyc"
+Provides-Extra: dev
+Requires-Dist: djangorestframework>=3.14; extra == "dev"
+Requires-Dist: pgvector>=0.2; extra == "dev"
+Requires-Dist: psycopg[binary]>=3.1; extra == "dev"
+Requires-Dist: insightface>=0.7; extra == "dev"
+Requires-Dist: onnxruntime>=1.16; extra == "dev"
+Requires-Dist: pillow>=10.0; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-django; extra == "dev"
+Dynamic: license-file
+
+# Django Camera Kit
+
+Document scanning and KYC face verification widgets for Django. Drop a real document scanner (live edge detection, manual corner adjustment, multi-page → PDF) into any existing `FileField`, no new models or endpoints required. Add live selfie/ID face verification with a server-side matching endpoint.
+
+[![Tests](https://img.shields.io/github/actions/workflow/status/Altius-Academy-SNC/django-camera-kit/tests.yml?branch=main&label=tests)](https://github.com/Altius-Academy-SNC/django-camera-kit/actions/workflows/tests.yml)
+[![PyPI version](https://img.shields.io/pypi/v/django-camera-kit.svg)](https://pypi.org/project/django-camera-kit/)
+[![License](https://img.shields.io/github/license/Altius-Academy-SNC/django-camera-kit.svg)](LICENSE)
+
+**[Documentation](https://altius-academy-snc.github.io/django-camera-kit)** | **[PyPI](https://pypi.org/project/django-camera-kit/)** | **[Source](https://github.com/Altius-Academy-SNC/django-camera-kit)**
+
+## Status
+
+Document scanning (this package's base install) and KYC identity verification (the `kyc` extra) are both implemented and tested. See the [documentation](https://altius-academy-snc.github.io/django-camera-kit) for the full guide, including the KYC module's security model and known MVP limitations.
+
+## Quick example
+
+```python
+# forms.py — any existing ModelForm, any existing FileField/ImageField
+from django import forms
+from django_camera_kit.widgets import DocumentScannerWidget
+
+from .models import Contract
+
+
+class ContractForm(forms.ModelForm):
+    class Meta:
+        model = Contract
+        fields = ["signed_document"]
+        widgets = {"signed_document": DocumentScannerWidget()}
+```
+
+```html
+<!-- template -->
+{{ form.media }}
+<form method="post" enctype="multipart/form-data">
+  {% csrf_token %}
+  {{ form }}
+  <button type="submit">Enregistrer</button>
+</form>
+```
+
+The widget replaces the plain file input with a "Scanner un document" button. Clicking it opens the camera, detects the document's edges live (OpenCV.js), lets the user drag the corners if detection misses, and supports adding several pages before assembling everything into a single PDF — written back into the same file input via the `DataTransfer` API. From the form's point of view, it's a normal file upload.
+
+## KYC quick example
+
+```bash
+pip install django-camera-kit[kyc]
+```
+
+```python
+# forms.py
+from django import forms
+from django_camera_kit.kyc.widgets import KYCVerificationWidget
+
+class SignupForm(forms.Form):
+    kyc_verification_id = forms.IntegerField(
+        widget=KYCVerificationWidget(verify_url="/kyc/verify/")
+    )
+```
+
+Requires PostgreSQL with the `pgvector` extension. Matching (face embeddings via YuNet + insightface) only ever happens server-side. See [KYC & Identity Verification](https://altius-academy-snc.github.io/django-camera-kit/guides/kyc/) for the full setup and security model.
+
+## Setup
+
+Two vendor JS files are required for the scan widget and not committed to this repo (binary build artifacts, pinned separately) — see [`django_camera_kit/static/django_camera_kit/vendor/README.md`](django_camera_kit/static/django_camera_kit/vendor/README.md) for exact files and versions to download.
+
+Requires Bootstrap (or Bootstrap Native) CSS/JS to already be loaded on the host page for button styling — `django-camera-kit` only ships the structural/positioning CSS for the scanner overlays themselves.
+
+## Roadmap
+
+1. ~~Scan MVP~~ — single page, manual corner adjustment, perspective warp
+2. Auto contour detection refinements
+3. Multi-page flow polish
+4. ~~KYC MVP~~ — selfie + ID capture, embedding comparison, head-movement liveness challenge
+5. Anti-deepfake hardening — server-verified liveness, passive scoring, multiple challenge types
+6. ~~Docs site~~ + PyPI release
+
+## License
+
+MIT

django_camera_kit-0.1.0/README.md

@@ -0,0 +1,80 @@
+# Django Camera Kit
+
+Document scanning and KYC face verification widgets for Django. Drop a real document scanner (live edge detection, manual corner adjustment, multi-page → PDF) into any existing `FileField`, no new models or endpoints required. Add live selfie/ID face verification with a server-side matching endpoint.
+
+[![Tests](https://img.shields.io/github/actions/workflow/status/Altius-Academy-SNC/django-camera-kit/tests.yml?branch=main&label=tests)](https://github.com/Altius-Academy-SNC/django-camera-kit/actions/workflows/tests.yml)
+[![PyPI version](https://img.shields.io/pypi/v/django-camera-kit.svg)](https://pypi.org/project/django-camera-kit/)
+[![License](https://img.shields.io/github/license/Altius-Academy-SNC/django-camera-kit.svg)](LICENSE)
+
+**[Documentation](https://altius-academy-snc.github.io/django-camera-kit)** | **[PyPI](https://pypi.org/project/django-camera-kit/)** | **[Source](https://github.com/Altius-Academy-SNC/django-camera-kit)**
+
+## Status
+
+Document scanning (this package's base install) and KYC identity verification (the `kyc` extra) are both implemented and tested. See the [documentation](https://altius-academy-snc.github.io/django-camera-kit) for the full guide, including the KYC module's security model and known MVP limitations.
+
+## Quick example
+
+```python
+# forms.py — any existing ModelForm, any existing FileField/ImageField
+from django import forms
+from django_camera_kit.widgets import DocumentScannerWidget
+
+from .models import Contract
+
+
+class ContractForm(forms.ModelForm):
+    class Meta:
+        model = Contract
+        fields = ["signed_document"]
+        widgets = {"signed_document": DocumentScannerWidget()}
+```
+
+```html
+<!-- template -->
+{{ form.media }}
+<form method="post" enctype="multipart/form-data">
+  {% csrf_token %}
+  {{ form }}
+  <button type="submit">Enregistrer</button>
+</form>
+```
+
+The widget replaces the plain file input with a "Scanner un document" button. Clicking it opens the camera, detects the document's edges live (OpenCV.js), lets the user drag the corners if detection misses, and supports adding several pages before assembling everything into a single PDF — written back into the same file input via the `DataTransfer` API. From the form's point of view, it's a normal file upload.
+
+## KYC quick example
+
+```bash
+pip install django-camera-kit[kyc]
+```
+
+```python
+# forms.py
+from django import forms
+from django_camera_kit.kyc.widgets import KYCVerificationWidget
+
+class SignupForm(forms.Form):
+    kyc_verification_id = forms.IntegerField(
+        widget=KYCVerificationWidget(verify_url="/kyc/verify/")
+    )
+```
+
+Requires PostgreSQL with the `pgvector` extension. Matching (face embeddings via YuNet + insightface) only ever happens server-side. See [KYC & Identity Verification](https://altius-academy-snc.github.io/django-camera-kit/guides/kyc/) for the full setup and security model.
+
+## Setup
+
+Two vendor JS files are required for the scan widget and not committed to this repo (binary build artifacts, pinned separately) — see [`django_camera_kit/static/django_camera_kit/vendor/README.md`](django_camera_kit/static/django_camera_kit/vendor/README.md) for exact files and versions to download.
+
+Requires Bootstrap (or Bootstrap Native) CSS/JS to already be loaded on the host page for button styling — `django-camera-kit` only ships the structural/positioning CSS for the scanner overlays themselves.
+
+## Roadmap
+
+1. ~~Scan MVP~~ — single page, manual corner adjustment, perspective warp
+2. Auto contour detection refinements
+3. Multi-page flow polish
+4. ~~KYC MVP~~ — selfie + ID capture, embedding comparison, head-movement liveness challenge
+5. Anti-deepfake hardening — server-verified liveness, passive scoring, multiple challenge types
+6. ~~Docs site~~ + PyPI release
+
+## License
+
+MIT

django_camera_kit-0.1.0/django_camera_kit/__init__.py

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

django_camera_kit-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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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;
+}