facekey 0.0.1__tar.gz

facekey-0.0.1/.gitattributes

@@ -0,0 +1,4 @@
+* text=auto eol=lf
+*.png binary
+*.jpg binary
+*.onnx binary

facekey-0.0.1/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.installed.cfg
+
+# Virtual envs
+.venv/
+venv/
+env/
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+
+# facekey local data (enrolled templates, downloaded model cache)
+.facekey/
+*.facekey.json

facekey-0.0.1/LICENSE

@@ -0,0 +1,36 @@
+MIT License
+
+Copyright (c) 2026 Adm145
+
+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.
+
+---
+
+NOTE ON BUNDLED MODEL WEIGHTS
+
+This MIT license covers the facekey source code only. facekey downloads and
+uses third-party model weights at runtime, which carry their own licenses:
+
+  * InsightFace "buffalo_l" / "buffalo_s" recognition and detection models are
+    released by their authors for NON-COMMERCIAL RESEARCH USE ONLY. Commercial
+    use requires a separate license from InsightFace
+    (recognition-oss-pack@insightface.ai). See EMBEDDER LICENSING in README.md.
+
+You are responsible for complying with the license of whichever model backend
+you choose to run.

facekey-0.0.1/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.5
+Name: facekey
+Version: 0.0.1
+Summary: Face-ID-style unlock for your app: enroll a face from several angles, then authenticate against a live camera frame.
+Project-URL: Homepage, https://github.com/Adm145/facekey
+Project-URL: Issues, https://github.com/Adm145/facekey/issues
+Author: Adm145
+License: MIT
+License-File: LICENSE
+Keywords: authentication,biometrics,face id,face recognition,face unlock,insightface,liveness
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Requires-Dist: insightface>=0.7.3
+Requires-Dist: numpy>=1.21
+Requires-Dist: onnxruntime>=1.15
+Requires-Dist: opencv-python-headless>=4.7
+Requires-Dist: platformdirs>=3.0
+Provides-Extra: camera
+Requires-Dist: opencv-python>=4.7; extra == 'camera'
+Provides-Extra: crypto
+Requires-Dist: cryptography>=41; extra == 'crypto'
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: gpu
+Requires-Dist: onnxruntime-gpu>=1.15; extra == 'gpu'
+Description-Content-Type: text/markdown
+
+# facekey
+
+> ⚠️ **Alpha — the API will change.** Pin an exact version if you depend on it.
+
+Face-ID-style unlock for your Python app. Enroll a face from a few angles, then
+on each unlock grab a frame from the camera, compare it to the enrolled
+template, and grant access on a match.
+
+```python
+from facekey import FaceLock
+
+lock = FaceLock()                 # single enrolled face, stored under a per-user data dir
+
+# one-time enrollment (needs a camera; pip install "facekey[camera]")
+lock.run_enrollment(camera=0, on_prompt=print)
+
+# later, guard something
+if lock.unlock(camera=0, timeout=5):
+    reveal_secret()
+else:
+    fall_back_to_password()
+```
+
+No camera in your process? Feed frames yourself — that's the real API; the
+camera helper is a thin convenience on top:
+
+```python
+import numpy as np
+from facekey import FaceLock
+
+lock = FaceLock()
+
+session = lock.enroll()
+while session.needs:                       # ["frontal", "left", "right", "up", "down"]
+    frame = my_capture()                   # H x W x 3 BGR ndarray, or JPEG/PNG bytes
+    result = session.capture(frame)
+    print(result.reason, "still need:", session.needs)
+session.commit()
+
+auth = lock.authenticate(my_capture())
+print(auth.granted, auth.score, auth.liveness)
+```
+
+## This is not a security boundary
+
+facekey uses an ordinary RGB camera. There is no infrared or depth sensing like
+a phone's Face ID. Passive liveness catches a casual printed photo or a phone
+screen held up to the lens, but it is beatable by replay video, masks, and
+deepfakes.
+
+Treat it as a **convenience factor**, not a lock:
+
+- Never make it the *only* thing standing between someone and sensitive data.
+- Always ship a PIN / password fallback.
+- Store only embeddings, never the enrollment images (facekey does this).
+- Let people delete their template (`lock.remove()`).
+- Get explicit consent before enrolling anyone. Face templates are biometric
+  data and are regulated (EU GDPR Art. 9, Illinois BIPA, others). Consent,
+  retention limits, and deletion are your responsibility.
+
+## Install
+
+```bash
+pip install facekey                 # core: frame-in, decision-out
+pip install "facekey[camera]"       # + OpenCV highgui for the camera helper / preview
+pip install "facekey[gpu]"          # + onnxruntime-gpu
+pip install "facekey[crypto]"       # + encryption at rest for stored templates
+```
+
+First use downloads the InsightFace model pack (~300 MB) into a local cache.
+Do it ahead of time with:
+
+```bash
+facekey download-models
+```
+
+`insightface` may build from source on some platforms; you need a C/C++
+toolchain if no wheel is available for your Python/OS.
+
+## EMBEDDER LICENSING — read before shipping commercially
+
+The default recognition backend is InsightFace **`buffalo_l`**. Its *code* is
+MIT, but its *pretrained weights* are released **for non-commercial research use
+only** (the training datasets forbid commercial use). Commercial use needs a
+license from InsightFace: `recognition-oss-pack@insightface.ai`.
+
+facekey emits a `FaceKeyLicenseWarning` the first time the default backend
+loads. To use facekey in a commercial product without that license, supply a
+differently-licensed embedder:
+
+```python
+from facekey import FaceLock
+from facekey.embedders import Embedder   # implement this protocol over your own model
+
+lock = FaceLock(embedder=MyPermissiveArcFace())
+```
+
+Suppress the warning (once you understand the terms) with
+`FACEKEY_SUPPRESS_LICENSE_WARNING=1` in the environment.
+
+## API sketch
+
+| Call | Purpose |
+|---|---|
+| `FaceLock(store=None, *, threshold=0.45, liveness=True, model="buffalo_l", max_enrollees=1, gpu=False)` | Construct a lock. `store`: `None` → per-user data dir, a path, or a `Store` instance. |
+| `lock.enroll(label="default") -> EnrollmentSession` | Start guided multi-angle enrollment. |
+| `session.capture(frame) -> CaptureResult` / `session.needs` / `session.commit()` | Feed frames until every pose bucket is covered, then persist. |
+| `lock.authenticate(frame, enrollee=None) -> AuthResult` | 1:1 verify. `enrollee` optional while only one face is enrolled. |
+| `lock.identify(frame) -> AuthResult` | 1:N — best match across all enrolled faces. |
+| `lock.unlock(camera=0, timeout=5) -> bool` | Camera helper: grab frames until match or timeout. |
+| `lock.run_enrollment(camera=0, on_prompt=print)` | Camera helper: drives the "turn your head" flow. |
+| `lock.enrolled()` / `lock.is_enrolled()` / `lock.remove(label="default")` | Manage templates. |
+
+`max_enrollees` is `1` today. The store, matching, and `identify()` are already
+multi-face internally — raise the cap (up to a handful) when you want a shared
+device.
+
+## Tuning the threshold
+
+`threshold` is cosine similarity on L2-normalized embeddings; higher is
+stricter. `0.45` is a deliberately conservative default for an auth use case.
+Lower it if legitimate users are rejected too often (higher false-accept rate),
+raise it to make impostor matches harder (higher false-reject rate). Measure on
+your own camera and lighting before trusting a number.
+
+## Status
+
+Alpha. `matching`, `stores`, `enrollment`, `models`, `errors` are implemented;
+`embedders.insightface`, `liveness`, and `camera` are minimal and expected to
+change. Passive liveness currently ships a lightweight texture heuristic
+(`HeuristicLiveness`); a MiniFASNet backend is the planned upgrade.
+
+## License
+
+MIT for the source (see `LICENSE`). Model weights carry their own terms — see
+EMBEDDER LICENSING above.

facekey-0.0.1/README.md

@@ -0,0 +1,136 @@
+# facekey
+
+> ⚠️ **Alpha — the API will change.** Pin an exact version if you depend on it.
+
+Face-ID-style unlock for your Python app. Enroll a face from a few angles, then
+on each unlock grab a frame from the camera, compare it to the enrolled
+template, and grant access on a match.
+
+```python
+from facekey import FaceLock
+
+lock = FaceLock()                 # single enrolled face, stored under a per-user data dir
+
+# one-time enrollment (needs a camera; pip install "facekey[camera]")
+lock.run_enrollment(camera=0, on_prompt=print)
+
+# later, guard something
+if lock.unlock(camera=0, timeout=5):
+    reveal_secret()
+else:
+    fall_back_to_password()
+```
+
+No camera in your process? Feed frames yourself — that's the real API; the
+camera helper is a thin convenience on top:
+
+```python
+import numpy as np
+from facekey import FaceLock
+
+lock = FaceLock()
+
+session = lock.enroll()
+while session.needs:                       # ["frontal", "left", "right", "up", "down"]
+    frame = my_capture()                   # H x W x 3 BGR ndarray, or JPEG/PNG bytes
+    result = session.capture(frame)
+    print(result.reason, "still need:", session.needs)
+session.commit()
+
+auth = lock.authenticate(my_capture())
+print(auth.granted, auth.score, auth.liveness)
+```
+
+## This is not a security boundary
+
+facekey uses an ordinary RGB camera. There is no infrared or depth sensing like
+a phone's Face ID. Passive liveness catches a casual printed photo or a phone
+screen held up to the lens, but it is beatable by replay video, masks, and
+deepfakes.
+
+Treat it as a **convenience factor**, not a lock:
+
+- Never make it the *only* thing standing between someone and sensitive data.
+- Always ship a PIN / password fallback.
+- Store only embeddings, never the enrollment images (facekey does this).
+- Let people delete their template (`lock.remove()`).
+- Get explicit consent before enrolling anyone. Face templates are biometric
+  data and are regulated (EU GDPR Art. 9, Illinois BIPA, others). Consent,
+  retention limits, and deletion are your responsibility.
+
+## Install
+
+```bash
+pip install facekey                 # core: frame-in, decision-out
+pip install "facekey[camera]"       # + OpenCV highgui for the camera helper / preview
+pip install "facekey[gpu]"          # + onnxruntime-gpu
+pip install "facekey[crypto]"       # + encryption at rest for stored templates
+```
+
+First use downloads the InsightFace model pack (~300 MB) into a local cache.
+Do it ahead of time with:
+
+```bash
+facekey download-models
+```
+
+`insightface` may build from source on some platforms; you need a C/C++
+toolchain if no wheel is available for your Python/OS.
+
+## EMBEDDER LICENSING — read before shipping commercially
+
+The default recognition backend is InsightFace **`buffalo_l`**. Its *code* is
+MIT, but its *pretrained weights* are released **for non-commercial research use
+only** (the training datasets forbid commercial use). Commercial use needs a
+license from InsightFace: `recognition-oss-pack@insightface.ai`.
+
+facekey emits a `FaceKeyLicenseWarning` the first time the default backend
+loads. To use facekey in a commercial product without that license, supply a
+differently-licensed embedder:
+
+```python
+from facekey import FaceLock
+from facekey.embedders import Embedder   # implement this protocol over your own model
+
+lock = FaceLock(embedder=MyPermissiveArcFace())
+```
+
+Suppress the warning (once you understand the terms) with
+`FACEKEY_SUPPRESS_LICENSE_WARNING=1` in the environment.
+
+## API sketch
+
+| Call | Purpose |
+|---|---|
+| `FaceLock(store=None, *, threshold=0.45, liveness=True, model="buffalo_l", max_enrollees=1, gpu=False)` | Construct a lock. `store`: `None` → per-user data dir, a path, or a `Store` instance. |
+| `lock.enroll(label="default") -> EnrollmentSession` | Start guided multi-angle enrollment. |
+| `session.capture(frame) -> CaptureResult` / `session.needs` / `session.commit()` | Feed frames until every pose bucket is covered, then persist. |
+| `lock.authenticate(frame, enrollee=None) -> AuthResult` | 1:1 verify. `enrollee` optional while only one face is enrolled. |
+| `lock.identify(frame) -> AuthResult` | 1:N — best match across all enrolled faces. |
+| `lock.unlock(camera=0, timeout=5) -> bool` | Camera helper: grab frames until match or timeout. |
+| `lock.run_enrollment(camera=0, on_prompt=print)` | Camera helper: drives the "turn your head" flow. |
+| `lock.enrolled()` / `lock.is_enrolled()` / `lock.remove(label="default")` | Manage templates. |
+
+`max_enrollees` is `1` today. The store, matching, and `identify()` are already
+multi-face internally — raise the cap (up to a handful) when you want a shared
+device.
+
+## Tuning the threshold
+
+`threshold` is cosine similarity on L2-normalized embeddings; higher is
+stricter. `0.45` is a deliberately conservative default for an auth use case.
+Lower it if legitimate users are rejected too often (higher false-accept rate),
+raise it to make impostor matches harder (higher false-reject rate). Measure on
+your own camera and lighting before trusting a number.
+
+## Status
+
+Alpha. `matching`, `stores`, `enrollment`, `models`, `errors` are implemented;
+`embedders.insightface`, `liveness`, and `camera` are minimal and expected to
+change. Passive liveness currently ships a lightweight texture heuristic
+(`HeuristicLiveness`); a MiniFASNet backend is the planned upgrade.
+
+## License
+
+MIT for the source (see `LICENSE`). Model weights carry their own terms — see
+EMBEDDER LICENSING above.

facekey-0.0.1/examples/desktop_unlock.py

@@ -0,0 +1,29 @@
+"""Enroll once, then gate a secret behind a face unlock.
+
+    pip install "facekey[camera]"
+    python examples/desktop_unlock.py
+"""
+
+from __future__ import annotations
+
+from facekey import FaceLock
+
+SECRET = "the launch codes are 0000"
+
+
+def main() -> None:
+    lock = FaceLock()  # stores the template under your per-user data dir
+
+    if not lock.is_enrolled():
+        print("No face on file - starting enrollment.")
+        lock.run_enrollment(camera=0, on_prompt=print)
+
+    print("\nLook at the camera to unlock...")
+    if lock.unlock(camera=0, timeout=6):
+        print("Unlocked:", SECRET)
+    else:
+        print("Denied. Fall back to a password here.")
+
+
+if __name__ == "__main__":
+    main()

facekey-0.0.1/examples/web_fastapi.py

@@ -0,0 +1,67 @@
+"""Face unlock over HTTP: the browser captures frames, this server matches them.
+
+    pip install facekey fastapi "uvicorn[standard]" python-multipart
+    uvicorn examples.web_fastapi:app --reload
+
+POST a still image (multipart field ``frame``) to:
+  /enroll/capture   until the response shows no remaining ``needs``
+  /enroll/commit    to persist
+  /authenticate     to check a face
+
+This keeps the frame-based API server-side; no camera on the host is involved.
+Enrollment state is held in memory here for brevity - use a real session store
+in production.
+"""
+
+from __future__ import annotations
+
+from fastapi import FastAPI, File, UploadFile
+
+from facekey import FaceLock
+from facekey.errors import FaceKeyError
+
+app = FastAPI(title="facekey web example")
+lock = FaceLock()
+_session = {"obj": None}
+
+
+@app.post("/enroll/capture")
+async def enroll_capture(frame: UploadFile = File(...)):
+    if _session["obj"] is None:
+        _session["obj"] = lock.enroll()
+    result = _session["obj"].capture(await frame.read())
+    return {
+        "accepted": result.accepted,
+        "reason": result.reason,
+        "bucket": result.bucket.value if result.bucket else None,
+        "needs": result.needs,
+        "progress": result.progress,
+    }
+
+
+@app.post("/enroll/commit")
+async def enroll_commit():
+    session = _session["obj"]
+    if session is None:
+        return {"error": "no enrollment in progress"}
+    try:
+        template = session.commit()
+    except FaceKeyError as exc:
+        return {"error": str(exc)}
+    lock.store.put(template)
+    _session["obj"] = None
+    return {"enrolled": template.label, "poses": sorted(template.embeddings)}
+
+
+@app.post("/authenticate")
+async def authenticate(frame: UploadFile = File(...)):
+    try:
+        result = lock.authenticate(await frame.read())
+    except FaceKeyError as exc:
+        return {"granted": False, "reason": str(exc)}
+    return {
+        "granted": result.granted,
+        "score": result.score,
+        "liveness": result.liveness,
+        "reason": result.reason,
+    }

facekey-0.0.1/pyproject.toml

@@ -0,0 +1,73 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "facekey"
+version = "0.0.1"
+description = "Face-ID-style unlock for your app: enroll a face from several angles, then authenticate against a live camera frame."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Adm145" }]
+keywords = [
+    "face recognition",
+    "face unlock",
+    "face id",
+    "authentication",
+    "biometrics",
+    "liveness",
+    "insightface",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Image Recognition",
+    "Topic :: Security",
+]
+dependencies = [
+    "numpy>=1.21",
+    "opencv-python-headless>=4.7",
+    "insightface>=0.7.3",
+    "onnxruntime>=1.15",
+    "platformdirs>=3.0",
+]
+
+[project.optional-dependencies]
+# Full OpenCV build: adds the highgui preview window used by the camera helper.
+# The base install already has cv2.VideoCapture via opencv-python-headless.
+camera = ["opencv-python>=4.7"]
+gpu = ["onnxruntime-gpu>=1.15"]
+crypto = ["cryptography>=41"]
+dev = ["pytest>=7", "ruff>=0.4", "build>=1.0"]
+
+[project.scripts]
+facekey = "facekey.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/Adm145/facekey"
+Issues = "https://github.com/Adm145/facekey/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/facekey"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+filterwarnings = [
+    "ignore::facekey.errors.FaceKeyLicenseWarning",
+    "ignore::facekey.errors.WeakLivenessWarning",
+]

facekey-0.0.1/src/facekey/__init__.py

@@ -0,0 +1,71 @@
+"""facekey - Face-ID-style unlock for your app.
+
+See the README for the security caveats and model licensing. Quick start::
+
+    from facekey import FaceLock
+
+    lock = FaceLock()
+    lock.run_enrollment(camera=0, on_prompt=print)
+    if lock.unlock(camera=0, timeout=5):
+        ...
+"""
+
+from __future__ import annotations
+
+from .core import FaceLock, __version__
+from .embedders import Embedder, get_embedder, register
+from .enrollment import EnrollmentSession
+from .errors import (
+    EnrollmentIncomplete,
+    FaceKeyError,
+    FaceKeyLicenseWarning,
+    LivenessCheckFailed,
+    LowQualityFrame,
+    ModelDownloadError,
+    MultipleFacesDetected,
+    NoFaceDetected,
+    NotEnrolled,
+    StoreFull,
+    WeakLivenessWarning,
+)
+from .liveness import HeuristicLiveness, LivenessChecker, NullLiveness
+from .matching import DEFAULT_THRESHOLD, cosine_similarity
+from .models import AuthResult, CaptureResult, FaceObservation, FaceTemplate, PoseBucket
+from .stores import FileStore, SQLiteStore, Store
+
+__all__ = [
+    "__version__",
+    "FaceLock",
+    "EnrollmentSession",
+    "AuthResult",
+    "CaptureResult",
+    "FaceObservation",
+    "FaceTemplate",
+    "PoseBucket",
+    "DEFAULT_THRESHOLD",
+    "cosine_similarity",
+    # embedders
+    "Embedder",
+    "get_embedder",
+    "register",
+    # liveness
+    "LivenessChecker",
+    "HeuristicLiveness",
+    "NullLiveness",
+    # stores
+    "Store",
+    "FileStore",
+    "SQLiteStore",
+    # errors / warnings
+    "FaceKeyError",
+    "NoFaceDetected",
+    "MultipleFacesDetected",
+    "LowQualityFrame",
+    "LivenessCheckFailed",
+    "NotEnrolled",
+    "EnrollmentIncomplete",
+    "StoreFull",
+    "ModelDownloadError",
+    "FaceKeyLicenseWarning",
+    "WeakLivenessWarning",
+]

facekey-0.0.1/src/facekey/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())