@richard.fadiora/liveness-detection 1.0.5 → 2.0.1

package/README.md

@@ -0,0 +1,192 @@
+# 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 **60-second timer** starts immediately.
+
+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:
+
+```js
+onComplete(true)
+```
+
+### If verification fails:
+- The UI displays a failure message
+- The component triggers:
+
+```js
+onComplete(false)
+```
+
+---
+
+## 📦 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 |
+
+---
+
+## 🧩 Usage Example
+
+```jsx
+import { LivenessSDK } from "./LivenessSDK";
+
+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: **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.