Skip to content

mkbrown261/FaceAccess

BranchesTags

Repository files navigation

FaceAccess — AI-Enhanced Facial Recognition Access Control System v4.2

Project Overview

A complete facial recognition-based access control system with a multi-model biometric pipeline (ArcFace + InsightFace + FaceNet), AI Trust Engine v4, predictive behavioral analysis, real-time anomaly detection, a dedicated internal Developer Testing Lab, and a full legal compliance framework covering privacy, biometrics, SMS, and AI transparency.

Production: https://faceaccess.pages.dev
Home Dashboard: https://faceaccess.pages.dev/home/dashboard
Mobile App: https://faceaccess.pages.dev/home/mobile
🔬 Dev Lab: https://faceaccess.pages.dev/dev-lab

📋 Legal Pages

Page URL Status
Privacy Policy /legal/privacy ✅ Live
Terms of Use /legal/terms ✅ Live
SMS Consent Agreement /legal/sms-consent ✅ Live
Biometric Data Retention Policy /legal/biometric-retention ✅ Live
AI & Facial Recognition Disclosure /legal/ai-disclosure ✅ Live
Enterprise Security Compliance /legal/enterprise-security ✅ Live

✅ Completed Features

⚖️ Legal Compliance Framework (v1.0 — NEW)

Full legal policy ecosystem covering BIPA, CCPA, TCPA, and GDPR requirements.

6 Legal Pages (all live at /legal/*):

  • Privacy Policy — Biometric data handling, SMS communications, data rights, contact information
  • Terms of Use — Service agreement, biometric consent, SMS consent, acceptable use, limitation of liability
  • SMS Consent Agreement — Twilio-compliant TCPA consent language, STOP/HELP keywords, opt-out instructions, message types
  • Biometric Data Retention Policy — BIPA-compliant written retention schedule, 3-year max, 30-day deletion SLA, IL/TX/WA/CA compliance
  • AI & Facial Recognition Disclosure — Algorithm transparency, 128-dim embeddings, anti-spoof threshold (0.72), accuracy limitations, demographic fairness
  • Enterprise Security Compliance — Cloudflare edge security, AES-256 encryption, RBAC, rate limiting, SOC2/ISO27001 vendor compliance

Consent Checkboxes at Every Signup Entry Point: All 4 registration flows now include dual consent checkboxes:

  1. ✅ Required: Terms of Use + Privacy Policy + Biometric data consent
  2. ☐ Optional: SMS text message consent (TCPA-compliant)

Registration flows updated:

  • Business Registration (bizDoRegister) — validates biz-reg-consent-terms required
  • Home Registration (homeDoRegister) — validates home-reg-consent-terms required
  • Mobile Registration (mobDoRegister) — validates mob-reg-consent-terms required
  • Home Onboarding Step 0 (saveAccount) — validates ob-consent-terms required
  • sms_consent flag passed to all backend registration APIs

🔬 Developer Testing Lab (v1.0 — NEW at /dev-lab)

Internal sandbox environment for validating biometric pipeline accuracy, enrollment quality, and trust engine logic — fully isolated from production data.

Six integrated panels:

  1. Face Enrollment Panel

    • USB webcam / laptop camera / optional RTSP stream connection
    • Start/stop/switch camera controls with real-time feed
    • Live quality metrics: brightness, sharpness, anti-spoof score
    • 7-angle progress dots (center, left, right, up, down, left_up, right_up)
    • One-click capture per angle or Auto-Enroll (captures all 7 angles automatically)
    • Embedding generation via frame pixel analysis (128-dim L2-normalized vector)
    • Clear embeddings per profile

  2. Authentication Test Panel

    • Three test modes: Live Camera, Demo (simulated), Manual
    • Simulated lock selector (Lab-Door-01/02, Lab-Entrance, Server-Room)
    • BLE proximity + Wi-Fi match toggles
    • Full pipeline simulation: cosine similarity → multi-model scoring → trust calculation
    • Debug mode toggle for raw pipeline values

  3. Lock Simulation

    • Animated Access Granted — Door Unlocked (green unlock + pulse glow)
    • Access Denied shake animation (red pulse)
    • Pending approval state indicator

  4. Confidence Visualization Panel

    • Three doughnut rings: Identity Confidence, Liveness, Trust Score
    • 8-metric score bars: ArcFace, InsightFace, FaceNet, Combined, Final, Liveness, Anti-Spoof, Proximity
    • Full breakdown table with visual bars per metric
    • Confidence history line chart (last 20 tests)
    • Pipeline trace: stage badges (edge → arcface → insightface → fusion → trust) + latency

  5. Security Log Panel

    • Real-time table: timestamp, result badge, matched user, similarity, combined confidence, trust tier/score, latency, lock, test mode
    • Stats bar: total, granted, denied, avg confidence, avg latency
    • Filter by result (granted/denied/pending)
    • Clear all logs

  6. Dev Controls Panel

    • Reset lab (clear embeddings + logs, keep profiles)
    • Delete all test profiles
    • Debug mode (raw model values in debug console)
    • Pipeline config display (all thresholds)
    • Debug console (monospace live output)
    • Lab statistics dashboard

Dev Lab API endpoints (10 routes under /api/devlab/):

GET/POST     /api/devlab/profiles         — CRUD test profiles (name, email, role, device ID)
GET          /api/devlab/profiles/:id     — Single profile
DELETE       /api/devlab/profiles/:id     — Delete profile + embeddings
POST         /api/devlab/enroll/:id       — Store face embedding (64-512 floats)
GET          /api/devlab/enroll/:id       — List embeddings for profile
DELETE       /api/devlab/enroll/:id       — Clear all embeddings for profile
POST         /api/devlab/authenticate     — Full auth pipeline simulation
GET/DELETE   /api/devlab/logs             — Security log (filter by decision)
GET          /api/devlab/stats            — Aggregate lab statistics
DELETE       /api/devlab/reset            — Full lab reset

DB tables: devlab_profiles, devlab_embeddings, devlab_test_log, devlab_sessions

Multi-Model Biometric Pipeline (v4.0 — Latest)

  • Tiered Recognition Pipeline: Face detection → Alignment → ArcFace primary → Cosine check → If borderline → InsightFace secondary → FaceNet tertiary
  • ArcFace ResNet100 — 512-dim embeddings, primary model (weight 50%), angular margin softmax, highest discriminability
  • InsightFace MobileNetV3 — 256-dim embeddings, secondary model (weight 30%), fast inference for borderline cases
  • FaceNet Inception — 128-dim embeddings, tertiary model (weight 20%), invoked only when first two disagree
  • Score Fusion Formula: combined = ArcFace×0.50 + InsightFace×0.30 + FaceNet×0.20
  • Borderline Detection — Scores 60-90% trigger secondary verification automatically
  • Model Agreement Score — Measures consistency between all active models; low agreement flags suspicious cases
  • Edge AI Preprocessing — Face alignment, landmark detection, anti-spoof pre-check run on-device before cloud verification
  • Continuous Learning Engine — EMA-based template adaptation after successful authentications (α=0.05 update per success)
  • Full Audit Logging — Every authentication decision logged with all model scores, latency, and decision path

AI Trust Engine v4

  • Multi-Model Trust Formula: trust = face_avg×0.35 + behavioral×0.35 + predictive×0.20 − penalty×0.10
  • Per-Model Tracking — arcface_avg, insightface_avg stored per user in trust profiles
  • Trust Score History — Time-series of trust score changes for trend visualization
  • Tiers: trusted (≥85%) instant unlock; standard (≥60%); watchlist (≥40%) extra verification; blocked (<40%)
  • EMA Adaptation — α=0.15 for stable trust evolution
  • Behavioral Model — Continuous learning of typical arrival times, doors, device proximity patterns
  • Behavioral Drift Detection — Compares recent vs 7-day prior pattern distributions; flags significant shifts

Biometric Audit Log (Compliance)

Every authentication decision records:

  • Decision: granted | denied | pending | error
  • All model scores: arcface_score, insightface_score, facenet_score, combined_confidence
  • anti_spoof_score, liveness_score, edge_confidence, quality_score
  • Pipeline trace: stage_reached (e.g., edge→arcface→insightface→fusion)
  • pipeline_latency_ms, model_agreement, is_borderline
  • Trust context: trust_score, trust_tier, behavioral_typical, anomaly_score
  • Device signals: ble_detected, wifi_matched, proximity_score

AI Intelligence Dashboard (v3.0+)

  • Multi-Model Pipeline Status Panel — Visual stage flow with per-model accuracy, avg latency, model agreement
  • Pipeline Performance Metrics — 7-day total verifications, borderline cases, latency distribution
  • Trust Engine Formula Display — Real-time weighted formula visualization
  • Trust Score Cards — Trusted / Standard / Watchlist / Anomalies count
  • User Trust Profile Modal — Multi-model biometric stats per user (ArcFace, InsightFace, FaceNet averages)
  • Behavioral Heatmap — 24×7 access frequency visualization
  • Arrival Predictions — Next predicted arrival per user
  • AI Recommendations — Auto-generated: revoke blocked, upgrade watchlist, renew guest passes
  • Anomaly Feed — Real-time anomaly events with resolve/acknowledge actions

Core Face Recognition

  • Liveness detection (eye-open ratio, motion history, challenge-response)
  • Anti-spoofing: contrast variance, Sobel texture, highlight ratio, screen artifact detection
  • Cosine similarity matching against AES-256 encrypted embeddings
  • Confidence tiers: High ≥85% (auto-grant), Medium 65–84% (triggers 2FA), Low <65% (denied)
  • Phone proximity verification (BLE + WiFi)
  • Multi-angle enrollment: 7 angles, 3 liveness challenges

FaceAccess Home

  • Multi-lock smart home security (August, Schlage, Yale, Nuki, Generic)
  • Real-time face recognition at door via FaceID Engine v2.0
  • Guest pass management with time windows and day restrictions
  • Remote approval: push notification → mobile approve/deny
  • Device registration + BLE proximity fingerprinting

Security & Privacy

  • AES-256 GCM encrypted biometric embeddings (Web Crypto API)
  • GDPR-compliant biometric erasure (DELETE /api/home/users/:id/face)
  • Server-side rate limiting: 10 attempts/min per lock
  • Client-side rate limiting: 5 attempts/min with 60s lockout
  • Hard rejection: anti-spoof score < 0.35, liveness < 0.50
  • No raw photos stored; only 512-dim normalized vectors

API Reference

Multi-Model Biometric (v4.0)

POST /api/home/recognize
  Body: { lock_id, arcface_score, insightface_score, facenet_score,
          combined_confidence, anti_spoof_score, liveness_score,
          edge_confidence, model_agreement, pipeline_latency_ms,
          stage_reached, is_borderline, ble_detected, wifi_matched,
          verification_version: "4.0" }

GET  /api/ai/pipeline/stats/:home_id   — 7-day pipeline performance metrics
GET  /api/ai/audit/:home_id            — Biometric audit log (compliance)
GET  /api/ai/audit/user/:user_id       — Per-user audit + model stats
POST /api/ai/multimodel/enroll/:user_id — Store multi-model embeddings
GET  /api/ai/multimodel/embeddings/:user_id — Enrollment metadata
GET  /api/ai/behavioral/model/:user_id — Behavioral model + drift analysis
GET  /api/ai/trust/history/:user_id   — Trust score trend history

AI Trust & Anomaly (v3.0)

GET  /api/ai/dashboard/:home_id        — Aggregated AI dashboard data
GET  /api/ai/trust/:home_id            — All trust profiles
GET  /api/ai/trust/user/:user_id       — Single user trust + hour distribution
POST /api/ai/trust/recalculate/:user_id — Force recalculate from history
GET  /api/ai/anomalies/:home_id        — Anomaly events
PUT  /api/ai/anomalies/:id/acknowledge
PUT  /api/ai/anomalies/:id/resolve
GET  /api/ai/predictions/:home_id      — Active predictive sessions
POST /api/ai/predictions/generate/:home_id
GET  /api/ai/recommendations/:home_id
GET  /api/ai/behavioral/:user_id       — Full behavioral analysis

Data Architecture

Storage: Cloudflare D1 (SQLite)

Core tables:

  • homes, home_users, home_devices, smart_locks, home_cameras
  • guest_passes, home_events, home_verifications, home_automations

AI tables (v3.0):

  • user_trust_profiles — Dynamic trust scores with EMA
  • behavioral_patterns — Raw time-series access events (w/ multi-model scores)
  • anomaly_events — Detected anomalies with severity and trust delta
  • predictive_sessions — Predicted arrival windows
  • ai_recommendations — Auto-generated access management suggestions

Multi-model tables (v4.0):

  • biometric_audit_log — Full compliance audit record for every authentication
  • multimodel_embeddings — Per-model embedding storage (ArcFace, InsightFace, FaceNet)
  • behavioral_models — Continuous learning state with drift detection
  • trust_score_history — Time-series of trust score changes

Multi-Model Pipeline Algorithms

Score Fusion:

combined = arcface × 0.50 + insightface × 0.30 + facenet × 0.20
adjusted = combined × (anti_spoof_adjustment) × (0.90 + edge_confidence × 0.10)

Trust Score:

trust = face_avg × 0.35 + behavioral × 0.35 + predictive × 0.20 - penalty × 0.10
EMA:  new = prev × 0.85 + current × 0.15  (α = 0.15)

Anomaly Types:

Type Severity Trust Delta
spoof_attempt critical −25%
repeated_failures high −15%
unusual_time high −12%
off_schedule medium −5%
behavioral_drift low −3%

Borderline Handling:

  • If ArcFace score 0.60–0.90 → automatically invoke InsightFace
  • If ArcFace & InsightFace disagree by >10% → invoke FaceNet
  • Model agreement = 1 - std_dev(all_scores) × 4

User Guide

Admin Dashboard

  1. Visit https://faceaccess.pages.dev/home/dashboard
  2. AI Intelligence tab → Multi-Model Pipeline Status, Trust Scores, Anomaly Feed
  3. Click on a user's trust profile to see per-model (ArcFace/InsightFace/FaceNet) biometric stats
  4. Face Recognition tab → Start camera → Click "Verify Identity" → See pipeline stages in result panel
  5. Anomaly Detection tab → Review and resolve security alerts

Mobile App

  1. Visit https://faceaccess.pages.dev/home/mobile
  2. Profile tab shows trust score gauge with security tier
  3. Home tab shows pending door approvals with confidence breakdown
  4. Approve/deny with biometric confirmation

API Integration (v4.0)

POST /api/home/recognize
{
  "lock_id": "lock-xxxx",
  "arcface_score": 0.91,
  "insightface_score": 0.88,
  "facenet_score": 0.87,
  "combined_confidence": 0.895,
  "anti_spoof_score": 0.88,
  "liveness_score": 0.94,
  "edge_confidence": 0.87,
  "model_agreement": 0.96,
  "pipeline_latency_ms": 342,
  "stage_reached": "edge→arcface→insightface→fusion",
  "is_borderline": false,
  "ble_detected": true,
  "verification_version": "4.0"
}

Deployment

  • Platform: Cloudflare Pages + D1 Database
  • Status: ✅ Active
  • Engine Version: v4.0
  • Tech Stack: Hono + TypeScript + TailwindCSS + Cloudflare D1
  • Last Updated: 2026-03-13

New Files (v4.0)

  • public/static/arcface-engine.js — Multi-model biometric pipeline (ArcFace, InsightFace, FaceNet, Edge AI, ContinuousLearning, AuditLogger)
  • migrations/0004_multimodel_schema.sql — biometric_audit_log, multimodel_embeddings, behavioral_models, trust_score_history + ALTER TABLE statements

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages