react-native-offline-face-auth

Offline facial recognition + liveness detection for React Native, built for field-personnel attendance on mid-range phones. Fully on-device matching, open-source models, and an AWS sync-and-purge pipeline.

Keywords: react-native face recognition · facial authentication · liveness detection · anti-spoofing · on-device ML · offline biometrics · TFLite · BlazeFace · FaceNet · MiniFASNet · face embedding · attendance tracking · field personnel · biometric authentication · edge ML · vision camera · encrypted storage · hardware security · AWS sync

---

Features

• Offline-first — templates are provisioned from the server once, then all recognition and liveness runs with no network connection.
• Hybrid liveness — passive anti-spoof (MiniFASNet two-scale) on every frame plus a randomized active challenge (blink / smile / turn head) to defeat photo and screen-replay fraud.
• No GPU required — TFLite models on the XNNPACK CPU delegate; works on 3 GB Android / iOS 12+ devices.
• Open-source only — no proprietary SDKs, no per-seat license fees.
• Hardware-backed security — Android Keystore (StrongBox) / iOS Keychain (Secure Enclave); templates encrypted at rest; cancelable biohash transform; tamper-evident audit log.
• < 10 MB model footprint — all five TFLite models combined.
• < 4 s end-to-end — gate + active challenge + N-frame analysis + matching.

---

Documentation

Document	Description
logic.md	Architecture & pipeline walkthrough — every stage explained
config.md	Full configuration reference — all fields, thresholds, and tuning guidance
CLAUDE.md	Contributor & AI guide — patterns, invariants, commands
models/README.md	Model provenance and licenses

---

Preview

Home Screen	Enrollment Dialog	Camera / Face Guide
Main menu — templates enrolled, pending sync visible	"Enter Person ID / Name" before capture starts	Live camera + oval guide overlay · quality gate hint

Sample app apk file

• Click here to download Sample App

---

Bundled Models

5 TFLite models ship inside the package. All run on the CPU (XNNPACK delegate) — no GPU required.

#	Model	File	Size	License	Role in pipeline
1	BlazeFace	blazeface.tflite	~0.5 MB	Apache-2.0	Face detection — bounding box + confidence, runs every frame
2	Face Mesh	face_mesh.tflite	~3.0 MB	Apache-2.0	468 landmark points + head pose (yaw / pitch / roll)
3	FaceNet-512	facenet_512.tflite	~4.0 MB	Apache-2.0 / MIT	512-dimensional face embedding for identity matching
4	MiniFASNet 2.7×	spoof_2_7.tflite	~1.0 MB	Apache-2.0	Passive liveness — texture-scale spoof detection (prints, screens)
5	MiniFASNet 4.0×	spoof_4_0.tflite	~1.0 MB	Apache-2.0	Passive liveness — geometry-scale spoof detection (3D masks, replays)
	Total		~9.5 MB

Pipeline role per model:

• BlazeFace — lightweight, runs on every frame (~25 ms). Triggers the rest of the pipeline only when a face is detected.
• Face Mesh — heavier (~40 ms), only runs during challenge and analyzing stages to save CPU.
• MiniFASNet ×2 — both branches run together during analyzing; their live_score outputs are averaged across 4 frames for a stable spoof decision.
• FaceNet — runs during analyzing to produce the probe embedding. L2-normalized 512-d vector enables fast cosine matching.

SHA-256 digests for all five files are in models/manifest.json and verified on every FaceAuth.init() call when readModelBytes is supplied.

---

Requirements

• React Native ≥ 0.72, Android 8.0+ (API 26), iOS 12+, ≥ 3 GB RAM

Peer dependencies:

Package	Version
@react-native-async-storage/async-storage	≥ 1.21.0
@react-native-community/netinfo	≥ 11.0.0
axios	≥ 1.0.0
react	≥ 18.0.0
react-native	≥ 0.72.0
react-native-fast-tflite	≥ 1.3.0
react-native-keychain	≥ 8.1.0
react-native-vision-camera	≥ 4.0.0
react-native-worklets-core	≥ 1.3.0
vision-camera-resize-plugin	≥ 3.0.0

---

Installation

npm install react-native-offline-face-auth \
  @react-native-async-storage/async-storage \
  @react-native-community/netinfo \
  axios \
  react-native-fast-tflite \
  react-native-keychain \
  react-native-vision-camera \
  react-native-worklets-core \
  vision-camera-resize-plugin

# iOS only
cd ios && pod install

Model bundling: copy the .tflite files from node_modules/react-native-offline-face-auth/models/ into your app's assets and load them with react-native-fast-tflite's useTensorflowModel.

Permissions: add NSCameraUsageDescription (iOS) and CAMERA (Android). Follow the react-native-vision-camera worklet setup guide.

---

Quick Start

import { FaceAuth, FaceAuthView } from 'react-native-offline-face-auth';
import { useTensorflowModel } from 'react-native-fast-tflite';

// 1. Initialize once at app startup
useEffect(() => {
  FaceAuth.init({
    awsSyncUrl:  'https://api.example.com/face-auth',
    deviceToken: 'your-device-token',
    deviceId:    'device-001',
  });
  // Pull enrolled templates while online
  FaceAuth.provision();
}, []);

// 2. Load TFLite models
const blazeface = useTensorflowModel(require('./models/blazeface.tflite'));
const faceMesh  = useTensorflowModel(require('./models/face_mesh.tflite'));
const facenet   = useTensorflowModel(require('./models/facenet_512.tflite'));
const spoof27   = useTensorflowModel(require('./models/spoof_2_7.tflite'));
const spoof40   = useTensorflowModel(require('./models/spoof_4_0.tflite'));

const models = { blazeface, faceMesh, embedding: facenet, liveness0: spoof27, liveness1: spoof40 };

// 3. Render the auth view — liveness, challenge, matching, and attendance logging are automatic
<FaceAuthView
  mode="identify"
  models={models}
  onResult={(r) => {
    if (r.ok) console.log('Authenticated:', r.personnelId, r.matchScore);
    else      console.log('Failed:', r.failureReason);
  }}
  onGuidance={(g) => setHint(g.message)}
/>

// 4. Manual sync (also fires automatically on network reconnect)
await FaceAuth.syncNow();

See example/App.tsx for a complete reference host app including enrollment, duplicate detection, and sync status display.

---

API

FaceAuth (static class)

Method	Description
init(config)	Open encrypted stores, derive the hardware key, verify model integrity, start the network watcher.
isInitialized()	Returns true after a successful init.
provision({ full? })	Pull enrolled templates from the server (incremental by default). No-op in offline-only mode.
needsReprovision()	true if templates were never synced or are older than templateTtlMs.
enrollLocal(personnelId, embeddingB64s)	Store face templates on-device — no server required. Pass base64 embeddings from AuthResult.embeddingB64.
checkDuplicate(embeddingB64)	Detect re-registration fraud before committing enrollment. Returns { isDuplicate, personnelId?, score }.
recordAttendance(result)	Append a signed, hash-chained attendance event (auto-called by FaceAuthView).
probeTransform(embedding)	Apply the device's cancelable transform to a probe embedding.
syncNow()	Push queued attendance events to AWS; purge acknowledged rows.
getPendingCount()	Number of attendance events awaiting sync.
getTemplateCount()	Number of enrolled templates on-device.
onSyncStatus(cb)	Subscribe to SyncStatus updates; returns an unsubscribe function.
dispose()	Stop the network watcher and release resources.

Components

• <FaceAuthView mode models onResult onGuidance /> — camera surface that runs a complete auth session.
• <FaceAuthModal ... /> — modal wrapper around FaceAuthView.
• useFaceAuth({ mode, models, onResult }) — headless hook (start / cancel / feed) for custom UIs.

Configuration

Pass a FaceAuthConfig object to FaceAuth.init(). Key fields:

Field	Default	Description
awsSyncUrl	—	AWS endpoint for sync. Omit for fully offline mode.
deviceToken	—	Per-device bearer token. Required with awsSyncUrl.
deviceId	'unknown-device'	Stamped onto every attendance event.
thresholds	see defaults	Override any subset of detection/liveness/matching thresholds.
challenges	all three	Pool for the random active challenge (blink, smile, turn_head).
cancelableKey	hardware key	Rotate to revoke all enrolled templates.

Full reference: config.md.

---

Server Contract

Endpoint	Request	Response
POST /provision	{ attestation, since }	{ mode:'full'|'delta', templates/upserts/removals, thresholds?, manifest?, syncedAt }
POST /attendance	{ events: StoredEvent[] }	{ acked: string[] }

• since = lastProvisionedAt (0 for first/forced-full sync).
• embedding values are base64 little-endian float32 from the same MobileFaceNet model + preprocessing as the device.
• thresholds in the provision response overrides local config remotely.
• manifest is the signed model manifest cached for the next boot integrity check.
• Only acknowledged attendance events are purged locally; the server must deduplicate on event id.

A zero-dependency mock backend is in server/index.js (port 8080).

---

Security

Property	Mechanism
No raw images on disk	Only 512-d embeddings stored
Hardware-backed encryption key	Android Keystore (StrongBox) / iOS Keychain (Secure Enclave)
Encrypted at rest	HMAC-SHA256 keystream cipher per entry
Revocable templates	Cancelable biohash — rotate key to revoke all
Tamper-evident log	SHA-256 hash chain + HMAC signature per event
Model integrity	SHA-256 of every .tflite verified on boot
Passive anti-spoof	MiniFASNet two-scale (texture + geometry attacks)
Active anti-spoof	Randomized blink / smile / turn challenge

---

License

MIT. Bundled TFLite models are Apache-2.0 / MIT — see models/README.md for provenance and per-model licenses.