@richard.fadiora/liveness-detection 4.2.11 → 4.2.13

package/dist/angular/README.md

@@ -0,0 +1,294 @@
+# Liveness Detection SDK
+
+A cross-framework **liveness detection SDK** that performs randomized user challenges and verifies real-user presence via a backend anti-spoofing API. Works with **React** and **Angular** via framework-specific wrappers while the **core engine is framework-agnostic**.
+
+This version introduces:
+
+- **Headless mode** for fully custom UI  
+- Robust **challenge sequencing**  
+- **Configurable thresholds** for `Smile`, `Blink`, and `Turn_Head` challenges  
+- Sequential challenge execution with **strict timeout handling**  
+- Pause between steps for user feedback  
+- Cross-framework integration (React hook & Angular service)  
+
+---
+
+## 📌 Overview
+
+This SDK strengthens identity verification by combining:
+
+- Randomized challenge-response validation  
+- Sequential challenge execution  
+- Strict timeout enforcement  
+- Backend spoof detection  
+- Callback-based integration for easy usage  
+- Headless / fully customizable UI via render props (React)  
+- Configurable challenge thresholds  
+
+Protects against:
+
+- Presentation (photo) attacks  
+- Screen glare attacks  
+- Video replay/injection attacks  
+
+---
+
+## ⚙️ Architecture
+
+### Core Engine
+
+- `LivenessEngine` (framework-agnostic)  
+- Handles:
+  - Challenge sequence generation
+  - MediaPipe face & hand model detection
+  - Challenge validation (`Smile`, `Blink`, `Turn_Head`, `Thumbs_Up`)
+  - Face cropping
+  - Detection loop
+  - Final frame capture and backend verification
+- Can be used directly or via React/Angular wrappers
+
+### Framework Wrappers
+
+| Framework | Wrapper | Notes |
+|-----------|--------|------|
+| React     | `useLiveness` hook | Uses `webcamRef` and React state, supports render-prop customization |
+| Angular   | `LivenessService`  | Injectable service, exposes engine state and control methods. Must be imported with "@richard.fadiora/liveness-detection/angular |
+
+---
+
+## ⚙️ How It Works
+
+### 1️⃣ Challenge Initialization
+
+- Randomly selects **3 challenges** from the pool: `Smile`, `Blink`, `Turn_Head`, `Thumbs_Up`.  
+- Timer starts immediately (default **60 seconds**, configurable via `duration`).  
+- Each challenge is verified sequentially, with a brief pause between steps for feedback.  
+- If the timer expires, the session terminates and no frames are sent to the backend.
+
+### 2️⃣ Challenge Execution
+
+- Real-time validation using webcam input and MediaPipe models.  
+- Sequential verification ensures **no steps are skipped**.  
+- Developers can render custom UI via the **render prop** while using the same underlying logic.
+- Challenge thresholds are configurable through props:
+
+| Prop Name             | Default | Description                              |
+|-----------------------|---------|------------------------------------------|
+| `smileThreshold`      | 0.20    | Minimum smile width to count as valid    |
+| `blinkThreshold`      | 0.01    | Maximum eye aspect ratio to count as blink |
+| `minturnHeadThreshold`| 0.15    | Minimum yaw for right head turn detection      |
+| `maxturnHeadThreshold`| 0.85    | Maximum yaw for left head turn detection      |
+
+### 3️⃣ Backend Liveness Verification
+
+- Captures **5 frames** from the webcam after all challenges are complete.  
+- Frames sent to backend API (`apiUrl` prop).  
+- Backend performs spoof detection, glare detection, and video injection detection.
+
+---
+
+## ✅ Success & Failure Behavior
+
+### Success
+- UI (or custom component) shows success feedback.  
+- `onComplete` callback is triggered:
+```js
+onComplete({ success: true, image: frame, skinConfidence });
+```
+
+### Failure
+- UI shows failure message.  
+- `onError` callback is triggered:
+```js
+onError({ success: false, reason, skinConfidence: null });
+```
+- Component resets; user must start a new session.
+
+---
+
+## 📦 Props
+
+| Prop Name   | Type                         | Required | Description |
+|------------|-----------------------------|----------|-------------|
+| `apiUrl`   | `string`                     | Yes      | Backend endpoint used for liveness verification |
+| `onComplete` | `(result: object) => void`  | Yes      | Callback fired after verification succeeds |
+| `onError`  | `(result: object) => void`   | Yes      | Callback fired after verification fails |
+| `duration` | `number`                     | No       | Maximum time for all challenges (default: 60s) |
+| `render`   | `(sdk: object) => JSX.Element` | No      | Optional render prop for full UI customization |
+| `classNames` | `object`                   | No       | Optional CSS class names to customize default UI |
+| `smileThreshold`       | `number`     | No       | Minimum smile width for Smile challenge                  |
+| `blinkThreshold`       | `number`     | No       | Maximum eye aspect ratio for Blink challenge             |
+| `minturnHeadThreshold` | `number`     | No       | Minimum yaw for Turn_Head challenge                      |
+| `maxturnHeadThreshold` | `number`     | No       | Maximum yaw for Turn_Head challenge                      |
+
+
+---
+
+## 🧩 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) => console.log("Success:", result)}
+      onError={(error) => console.log("Failed:", error.reason)}
+      duration={60}
+    />
+  );
+}
+
+export default App;
+```
+
+### 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}: {sdk.sequence[sdk.currentStep]}</div>
+      <div>Time left: {sdk.timeLeft}s</div>
+      <button onClick={sdk.start}>Start</button>
+    </div>
+  )}
+/>
+```
+## 📤 Hook Return Values
+
+The `useLiveness` hook exposes the following values and control functions for managing the liveness detection session.
+
+| Name | Type | Description |
+|-----|------|-------------|
+| `webcamRef` | `ref` | React ref attached to the webcam component. Provides access to the live video stream used for face and hand detection as well as frame capture for verification. |
+| `status` | `string` | Represents the current state of the liveness session. Possible values include `loading`, `ready`, `capturing`, `verifying`, `success`, `error`, and `expired`. |
+| `errorMsg` | `string` | Contains the error message displayed when the liveness verification fails or when the system encounters an issue. |
+| `sequence` | `string[]` | The randomized sequence of liveness challenges selected for the current session. Three challenges are chosen from the challenge pool. |
+| `currentStep` | `number` | The index of the current challenge being performed within the challenge sequence. |
+| `timeLeft` | `number` | Remaining time (in seconds) before the session expires. The timer runs while the system is in the `capturing` state. |
+| `isStepTransitioning` | `boolean` | Indicates whether the system is currently transitioning between challenges. Used to briefly pause detection and provide UI feedback after a challenge is completed. |
+| `start` | `function` | Starts the liveness challenge session and begins the detection loop. |
+| `reset` | `function` | Resets the entire session, including the timer, challenge sequence, step index, and error state. |
+| `sendFinalProof` | `function` | Sends captured face frames to the backend verification API to perform the final liveness check. Normally triggered automatically after the last challenge is completed. |
+
+
+
+
+---
+
+## 🎨 Styling with `classNames`
+
+You can pass a `classNames` object to override the default UI classes:
+```js
+classNames={{
+  container: "liveness-container",
+  webcam: "liveness-webcam",
+  button: "liveness-button",
+  challenge: "liveness-challenge",
+  timer: "liveness-timer",
+  error: "liveness-error",
+  success: "liveness-success",
+}}
+```
+
+### CSS Example
+```css
+.liveness-container {
+  text-align: center;
+  background: #121212;
+  padding: 24px;
+  border-radius: 20px;
+  box-shadow: 0 10px 30px rgba(0, 0, 0, 0.5);
+  color: white;
+}
+.liveness-webcam {
+  border-radius: 20px;
+  border: 2px solid #007bff;
+  width: 100%;
+}
+.liveness-button {
+  padding: 12px 30px;
+  font-size: 16px;
+  font-weight: bold;
+  border-radius: 10px;
+  background: #28a745;
+  color: white;
+  border: none;
+  cursor: pointer;
+  margin-top: 10px;
+}
+.liveness-challenge {
+  margin: 5px 0;
+  font-weight: bold;
+  font-size: 40px;
+}
+.liveness-timer {
+  margin: 10px 0;
+  font-weight: bold;
+  font-size: 18px;
+}
+.liveness-error {
+  color: #ff4d4d;
+  margin-top: 20px;
+}
+.liveness-success {
+  color: #4caf50;
+  margin-top: 20px;
+}
+```
+
+---
+
+## ⏳ Timeout Rules
+
+- Maximum session duration: set via `duration` prop (default 60s).  
+- On timeout: challenge stops, state resets, backend verification is not triggered.
+
+---
+
+## 🔐 Security Architecture
+
+- **Client-side**: Randomized challenges, real-time gesture detection  
+- **Server-side**: Frame-based spoof analysis, glare detection, video injection detection  
+- **Session control**: Timeout enforcement, manual restart on failure  
+- Reduces false positives and prevents replay attacks.
+
+---
+
+## 📊 Verification Criteria
+
+- All 3 challenges completed  
+- All 5 frames successfully sent to backend  
+- Backend confirms: no spoofing, no glare, human skin texture, no video injection
+
+---
+
+## 🏗️ Integration Notes
+
+- Webcam permissions required  
+- Backend must accept 5 frames in expected format  
+- `apiUrl` must be reachable and have an endpoint `/v1/verify` 
+- CORS must be configured properly
+
+---
+
+## 🚀 Ideal Use Cases
+
+- KYC verification flows  
+- Identity onboarding  
+- Account recovery  
+- Secure login  
+- Financial / compliance apps
+
+---
+
+## 👨‍💻 Maintainer
+
+Fadiora Richard.
+