docs(architecture): client-side embedding + puzzle-as-layer (diagrams + docs)#22
Merged
ahmetabdullahgultekin merged 2 commits intoJun 12, 2026
Merged
Conversation
…& plan Update the verified architecture diagrams and the client-side ML strategy to the now-landed (flag-gated, default OFF) reality: - 01 (system-context/container): browser computes the Facenet512 embedding and uploads only the 512-vector when app.auth.client-side-embedding is ON; the biometric-processor description now reflects /verify-embedding + /enroll-embedding alongside the legacy image path; honesty note added with the data-minimization privacy framing. - 03 (biometric pipelines): face ENROLLMENT gains the /enroll-embedding branch (server skips stages 1-6); face VERIFICATION is now a two-path sequence keyed on ClientSideEmbeddingPolicy (vector upload vs legacy image), server still owns the verdict; new section 7 adds the PUZZLE auth-flow layer with the server-issued single-use anti-replay session (create -> submit -> verdict) plus the optional identity-binding and a flowchart of the anti-replay/composition properties. - CLIENT_SIDE_ML_PLAN.md -> v3.0: browser owns the authoritative embedding + puzzle-as-layer; supersedes the v2.0 D1/D2 pre-filter-only locks (v2 retained as a legacy appendix); honest privacy framing throughout. All 16 mermaid blocks validated with mermaid-cli.
…ent-side-2026-06-12
ahmetabdullahgultekin
deleted the
docs/architecture-client-side-2026-06-12
branch
ahmetabdullahgultekin
added a commit
that referenced
this pull request
Jun 12, 2026
…th sweep) (#23) Align the remaining architecture prose with the SP-G client-side-embedding truth already landed in the diagram pages (PR #22) and CLIENT_SIDE_ML_PLAN v3.0. - BIOMETRIC_ENGINE_ARCHITECTURE: EmbeddingComputer is Facenet512 ONNX (was labelled MobileFaceNet / geometry-512 fallback). The client-side path (flag app.auth.client-side-embedding, default OFF) computes the authoritative Facenet512 embedding in the browser and uploads only the 512-d vector; raw image never leaves the device; server keeps the image->Facenet512 fallback and owns match + liveness verdict + decision. - ADR 0004: add a 2026-06-11 amendment. Encoder (Facenet512, 512-d, cosine) unchanged; the new client-side path computes that SAME embedding in-browser and is authoritative when the flag is ON. Corrects the old 'client embedding is a different model/shape, never compared against face_embeddings' (true of the old geometry-512 pre-filter, NOT the new client Facenet512). - PLATFORM_CAPABILITY_MATRIX (Face Recognition): document both the legacy image-upload path and the client-side-embedding path (data minimization: only the 512-d vector uploaded); anti-spoofing names the active Biometric Puzzle (randomized, server re-scored). Server remains authoritative for the match + liveness verdict + accept/reject in every case. Honest framing throughout: data minimization (derived non-invertible 512-d embedding over TLS, Fernet at rest), NOT 'biometric data never leaves the device'.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Reviewed SP-G architecture diagrams and docs reflecting the landed client-side-embedding two-path and server-authoritative puzzle session.
Docs-only: Mermaid diagram updates (deployment architecture, biometric pipelines) and CLIENT_SIDE_ML_PLAN additions.