react-native-neural-face-auth 🛡️

A secure, 100% Offline & On-Premise biometric verification library for React Native.

This library bridges native machine learning frameworks (Google ML Kit & TensorFlow Lite) to perform real-time face detection, liveness checks, and neural-embedding matching directly on the device. No data is ever sent to a server.

🚀 Key Features

• 100% Offline & On-Premise: All processing happens on the device. No API keys, no cloud costs, and zero latency issues. Perfect for GDPR/privacy-compliant apps.
• Neural Face Matching: Uses MobileFaceNet models to generate high-accuracy embeddings for 1:1 identity verification.
• Liveness Detection: Built-in UI (LivenessCameraView) that prompts users to Blink or Smile to ensure they are real.
• 🕵️ Multi-Frame Anti-Spoofing: Optional integrity check that captures a "secret" early frame and compares it against the final capture to prevent photo-swapping attacks.
• Dynamic Geofencing: Strict location-based access control with configurable radius logic.

📦 Installation

npm install react-native-neural-face-auth
# or
yarn add react-native-neural-face-auth

🍎 iOS Setup (Important)

Install Pods

cd ios && pod install

Apple Silicon (M1/M2/M3) Users

If you encounter symbol not found or architecture errors, add this to your Podfile inside the post_install block:

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      # Force Simulator to use Rosetta mode for ML compatibility
      config.build_settings["EXCLUDED_ARCHS[sdk=iphonesimulator*]"] = "arm64"
    end
  end
end

🤖 Android Setup

Ensure you have camera and location permissions in AndroidManifest.xml:

<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

📖 How It Works

1) Offline & On-Premise Architecture

Unlike generic face APIs (like AWS Rekognition), this library bundles the TFLite models inside your app binary.

• Input: Image is passed from React Native to Native (ObjC/Java).
• Processing: ML Kit detects the face -> TFLite crops and generates a 192-float vector embedding.
• Comparison: Euclidean distance is calculated between the Source ID and the Camera Capture.
• Output: A Match/No-Match result is returned instantly.

2) Multi-Frame Integrity (Anti-Spoofing)

When enableMultiFrameLiveness is set to true:

• The camera silently captures a "Secret Snap" while the user is positioning their face.
• It captures the "Final Blink" when the liveness challenge is complete.
• The verifyFaces function compares Secret Snap vs. Final Blink.
• If the user tried to swap a photo or move a phone screen in front of the camera between these milliseconds, the check fails.

3) Geofencing with Dynamic Radius

You can enforce that a user must be within X meters of a specific location (e.g., an office building) to authenticate.

• The native module fetches the GPS coordinates securely.
• It calculates the Haversine distance between the Device Location and the Allowed Center.
• If Distance > Radius, the verification is rejected immediately (Status 403), even if the face matches.

💻 Usage

1) The Liveness Camera

Import the view to handle the UI interaction (Blink detection).

import { LivenessCameraView } from 'react-native-neural-face-auth';

<LivenessCameraView
  style={{ flex: 1 }}
  livenessMode="BLINK" // Options: "BLINK", "SMILE", "NONE"
  enableMultiFrameLiveness={true} // Enables the secret anti-spoofing frame
  onCapture={(event) => {
    const finalUri = event.nativeEvent.uri;
    const earlyUri = event.nativeEvent.earlyUri; // The secret frame
    console.log("Captured:", finalUri, earlyUri);
  }}
  onStatusChange={(event) => {
    console.log("Instruction:", event.nativeEvent.message); // e.g. "Move Closer"
  }}
/>

2) Verifying the Face (Identity + Geo + Integrity)

Once you have the images, run the verification.

import { verifyFaces, getCurrentLocation } from 'react-native-neural-face-auth';

const handleVerification = async () => {
  // 1. Get GPS (Optional)
  const location = await getCurrentLocation();

  // 2. Configure Verification
  const config = {
    livenessMode: 'NONE', // Already checked liveness in camera

    // Geofencing Config
    enableLocation: true,
    sourceLat: 40.7580,  // Allowed Center (e.g. Office)
    sourceLng: -73.9855,
    targetLat: location.latitude, // Current Device GPS
    targetLng: location.longitude,
    radius: 100 // Allow 100 meter radius
  };

  // 3. Run Verify
  // To check Integrity: Compare Secret Frame vs Final Frame first
  // To check Identity: Compare ID Card vs Final Frame
  const response = await verifyFaces(referenceImageUri, cameraImageUri, config);

  if (response.statusCode === 200) {
    if (response.result.isMatch) {
       console.log(`Matched! Accuracy: ${response.result.accuracy}%`);
    } else {
       console.log("Face did not match.");
    }
  } else if (response.statusCode === 403) {
    console.log("Geofence Violation! You are too far away.");
  }
};

📚 API Reference

verifyFaces(sourceUri, targetUri, config)

Performs the mathematical embedding comparison.

| Config Key | Type | Description | |-----------|------|-------------| | livenessMode | String | "BLINK", "SMILE", or "NONE". Enforces logic on static images. | | enableLocation | Boolean | If true, validates lat/lng distance. | | sourceLat | Number | The latitude of the ALLOWED location. | | sourceLng | Number | The longitude of the ALLOWED location. | | targetLat | Number | The latitude of the DEVICE. | | targetLng | Number | The longitude of the DEVICE. | | radius | Number | Allowed distance in meters. |

📷 LivenessCameraView Props

| Prop | Type | Description | |------|------|-------------| | livenessMode | String | "BLINK" (default) or "NONE". Determines the trigger to take photo. | | enableMultiFrameLiveness | Boolean | If true, captures an early frame before the final trigger. | | onCapture | Event | Returns { uri, earlyUri }. | | onStatusChange | Event | Returns { message, isCorrect } for UI feedback. |

📄 License

MIT © Vasanth