Liveness Detection Component

A React-based liveness detection component that performs randomized user challenges and verifies real-user presence via a backend anti-spoofing API.

📌 Overview

This component strengthens identity verification by combining:

• Randomized challenge-response validation
• Strict timeout enforcement
• Backend spoof detection
• Callback-based integration for easy usage

It protects against:

• Presentation (photo) attacks
• Screen glare attacks
• Video replay/injection attacks

⚙️ How It Works

1️⃣ Challenge Initialization

When the user clicks the "Start Challenge" button:

• The system randomly selects 3 challenges

• The challenges are chosen from a fixed pool of 4:

  • Smile
  • Blink
  • Turn_Head
  • Thumbs_Up

• A timer starts immediately. If you do not pass the duration property, it will default to 60 seconds.

If the timer expires before completion:

• The session is terminated
• The user must restart the process manually
• No frames are sent to the backend

2️⃣ Challenge Execution

• Challenges are validated in real-time using webcam input.
• The next challenge only begins after the current one is successfully completed.
• All 3 challenges must be completed within the 60-second window.

If successful, the component proceeds to backend verification.

3️⃣ Backend Liveness Verification

After all challenges are completed:

• The component captures 5 frames from the webcam.
• These frames are sent to the backend API defined by the apiUrl prop.
• The backend performs:
  • Spoof detection
  • Glare detection
  • Video injection detection

✅ Success & Failure Behavior

If verification succeeds:

• The UI displays: "Verification Passed"
• The component triggers:

onComplete(true)

If verification fails:

• The UI displays a failure message
• The component triggers:

onError(false)

This is because the parameters being passed for both completion and Error are the same: success, result, and skinConfidence.

📦 Props

| Prop Name | Type | Required | Description | |------------|----------------------------|----------|-------------| | apiUrl | string | Yes | Backend endpoint used for liveness verification | | onComplete | (result: boolean) => void | Yes | Callback fired after verification completes | | onError | (result: boolean) => void | Yes | Callback fired after verification flags error | | duration | int | No | Used for setting maximum time for the challenges to be completed |

🧩 Usage Example

import { LivenessSDK } from "@richard.fadiora/liveness-detection";

function App() {
  return (
    <LivenessSDK
      apiUrl="https://your-backend-api.com/liveness-check"
      onComplete={(result) => {
        if (result) {
          console.log("User verified successfully");
        } else {
          console.log("Liveness verification failed");
        }
      }}
    />
  );
}

export default App;

⏳ Timeout Rules

• Maximum session duration: Set in the duration property, else 60 seconds
• If time expires:
  • The challenge stops immediately
  • The verification state resets
  • User must click Start Challenge again
  • Backend verification will NOT be triggered

🔐 Security Architecture

This component uses a layered approach:

1. Client-side active verification

   • Randomized challenge selection
   • Real-time gesture detection

2. Server-side passive verification

   • Frame-based spoof analysis
   • Glare detection
   • Video injection detection

3. Strict session control

   • Timeout enforcement
   • Restart requirement on failure

This multi-layer strategy reduces false positives and prevents replay-based attacks.

📊 Verification Criteria

A verification is considered successful only if:

• 3 randomly selected challenges are completed
• All 5 frames are successfully sent to the backend
• Backend confirms:
  • No spoofing detected
  • No glare detected
  • Skin Texture is human
  • No video injection detected

🏗️ Integration Notes

• The component assumes webcam permissions are granted.
• The backend must accept 5 frames in the expected format.
• The apiUrl must be reachable from the client environment.
• Ensure CORS is properly configured on the backend.

🚀 Ideal Use Cases

• KYC verification flows
• Identity onboarding systems
• Account recovery flows
• Secure login systems
• Financial or compliance-based applications

👨‍💻 Maintainer

Maintained by Princeps Credit Systems Limited.