@richard.fadiora/liveness-detection 2.1.0 → 3.0.0

package/README.md

@@ -1,195 +1,155 @@
-# Liveness Detection Component
+# Liveness Detection SDK
 
 A React-based liveness detection component that performs randomized user challenges and verifies real-user presence via a backend anti-spoofing API.
 
+This version introduces headless mode, render-prop customization, robust sequential challenge handling, and timeout enforcement, giving developers full control over the UI while keeping the core verification logic encapsulated.
+
 ---
 
-## 📌 Overview
+## Overview
 
-This component strengthens identity verification by combining:
+The component strengthens identity verification using:
 
 - Randomized challenge-response validation
+- Real-time gesture detection via MediaPipe
+- Sequential verification to ensure no challenges are skipped
 - Strict timeout enforcement
 - Backend spoof detection
-- Callback-based integration for easy usage
+- Callback-based integration for success/failure handling
+- Optional headless mode for fully custom UI
 
 It protects against:
 
 - Presentation (photo) attacks
 - Screen glare attacks
-- Video replay/injection attacks
+- Video replay or injection attacks
 
 ---
 
-## ⚙️ How It Works
+## How It Works
 
-### 1️⃣ Challenge Initialization
+### Challenge Initialization
 
-When the user clicks the **"Start Challenge"** button:
+- Randomly selects 3 challenges from 4: Smile, Blink, Turn_Head, Thumbs_Up
+- Timer starts immediately (default 60s, configurable)
+- Challenges verified sequentially with brief pause between steps
+- Timer expiry terminates session and stops backend verification
 
-- The system randomly selects **3 challenges**
-- The challenges are chosen from a fixed pool of 4:
+### Challenge Execution
 
-  - `Smile`
-  - `Blink`
-  - `Turn_Head`
-  - `Thumbs_Up`
+- Validates challenges in real-time using MediaPipe
+- Sequential logic ensures no challenge is skipped
+- Optional render prop allows fully custom UI
 
-- A timer starts immediately. If you do not pass the **duration** property, it will default to 60 seconds.
+### Backend Liveness Verification
 
-If the timer expires before completion:
-- The session is terminated
-- The user must restart the process manually
-- No frames are sent to the backend
+- Captures 5 frames from webcam after all challenges
+- Sends frames to backend API for verification
+- Backend performs spoof, glare, and video injection detection
 
 ---
 
-### 2️⃣ Challenge Execution
+## Success & Failure Behavior
 
-- 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.
+**Success:**
+- UI displays success message
+- onComplete callback triggered with frame and skin confidence
 
-If successful, the component proceeds to backend verification.
+**Failure:**
+- UI displays error message
+- onError callback triggered with reason
+- Component resets for new session
 
 ---
 
-### 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
-onError(false)
-```
-This is because the parameters being passed for both completion and Error are the same: success, result, and skinConfidence.
-
----
-
-## 📦 Props
+## 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 |
+| `apiUrl` | `string` | Yes | Backend endpoint for verification |
+| `onComplete` | `(result: boolean) => void` | Yes | Callback on success |
+| `onError` | `(result: boolean) => void` | Yes | Callback on failure |
+| `duration` | `int` | No | Max time for challenges (default 60s) |
+| render` | `(result: boolean) => void` | No | Optional custom UI render prop |
+| `classNames` | `object` | No | Optional CSS classes for default UI |
 
 ---
 
-## 🧩 Usage Example
+## Usage Example
 
+**Default UI:**
 ```jsx
-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;
+import { LivenessSDK } from '@richard.fadiora/liveness-detection';
+
+<LivenessSDK
+  apiUrl="https://your-backend-api.com/liveness-check"
+  onComplete={(result) => console.log(result)}
+  onError={(error) => console.log(error.reason)}
+  duration={60}
+/>
 ```
 
----
-
-## ⏳ 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
+**Headless / Custom UI:**
+```jsx
+<LivenessSDK
+  apiUrl="https://your-backend-api.com/liveness-check"
+  onComplete={handleComplete}
+  onError={handleError}
+  render={(sdk) => (
+    <div>
+      <video ref={sdk.webcamRef} autoPlay playsInline muted />
+      <div>Step {sdk.currentStep + 1} of {sdk.sequence.length}: {sdk.sequence[sdk.currentStep]}</div>
+      <div>Time left: {sdk.timeLeft}s</div>
+      <button onClick={sdk.start}>Start</button>
+    </div>
+  )}
+/>
+```
 
 ---
 
-## 🔐 Security Architecture
-
-This component uses a layered approach:
+## Timeout Rules
 
-1. **Client-side active verification**
-   - Randomized challenge selection
-   - Real-time gesture detection
+- Max session duration: `duration` prop (default 60s)
+- Expiry stops challenge, resets state, requires restart, no backend call
 
-2. **Server-side passive verification**
-   - Frame-based spoof analysis
-   - Glare detection
-   - Video injection detection
+---
 
-3. **Strict session control**
-   - Timeout enforcement
-   - Restart requirement on failure
+## Security Architecture
 
-This multi-layer strategy reduces false positives and prevents replay-based attacks.
+1. Client-side: randomized challenges, real-time gesture detection
+2. Server-side: frame-based spoof, glare, and injection detection
+3. Strict session control: timeout enforcement, restart requirement
 
 ---
 
-## 📊 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
+## Verification Criteria
 
+- All 3 challenges completed
+- All 5 frames sent to backend
+- Backend confirms no spoofing, no glare, human skin, no video injection
 
 ---
 
-## 🏗️ Integration Notes
+## 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.
+- Webcam permissions required
+- Backend must accept 5 frames
+- apiUrl must be reachable and CORS-enabled
 
 ---
 
-## 🚀 Ideal Use Cases
+## Ideal Use Cases
 
 - KYC verification flows
-- Identity onboarding systems
-- Account recovery flows
+- Identity onboarding
+- Account recovery
 - Secure login systems
-- Financial or compliance-based applications
+- Financial/compliance applications
 
 ---
 
-## 👨‍💻 Maintainer
+## Maintainer
+
+Fadiora Richard.
 
-Maintained by Princeps Credit Systems Limited.