@richard.fadiora/liveness-detection 4.3.6 → 4.3.8

package/README.md

@@ -1,294 +1,229 @@
 # 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)  
+A cross-framework **liveness detection SDK** that performs randomized user challenges and verifies real-user presence via a backend anti-spoofing API.  
+This package provides a **framework-agnostic core** with optimized wrappers for **React ⚛️** and **Angular 🅰️**.
 
----
+* * *
+
+## 🚀 Key Features in v4.3.8
+
+
+
+*   📦 **Multi-Entry Support**: Dedicated subpaths for React and Angular to prevent framework leakage.
+    
+*   🎨 **Prop-Driven Styling**: Fully customizable UI using class name injection (Tailwind/Bootstrap friendly).
+    
+*   🧠 **Headless Mode**: Access core logic via hooks (React) or services (Angular) for 100% custom UI.
+    
+*   🅰️ **Standalone Angular Support**: Angular wrapper uses standalone components; no NgModules needed.
+    
+*   🔒 **Improved Security**: Enhanced challenge sequencing with strict timeout handling and backend frame verification.
+    
+
+* * *
 
 ## 📌 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  
+*   🎲 Randomized challenge-response validation
+    
+*   📋 Sequential challenge execution (Smile, Blink, Turn\_Head, Thumbs\_Up)
+    
+*   🧠 Real-time MediaPipe face & hand landmark detection
+    
+*   🛡️ Protection against presentation attacks (photo/video), glare, and replay attacks
+    
 
-Protects against:
+* * *
 
-- Presentation (photo) attacks  
-- Screen glare attacks  
-- Video replay/injection attacks  
+## 📦 Installation & Imports
 
----
 
-## ⚙️ Architecture
 
-### Core Engine
+`npm install @richard.fadiora/liveness-detection`
 
-- `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
+### Import Paths
 
-### 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 |
+| Target | Import Path |
+| --- | --- |
+| Pure Logic (Core) | @richard.fadiora/liveness-detection |
+| React Wrapper ⚛️ | @richard.fadiora/liveness-detection/react |
+| Angular Wrapper 🅰️ | @richard.fadiora/liveness-detection/angular |
 
----
+These entry points ensure framework-specific code stays isolated and bundles remain small.
 
-## ⚙️ How It Works
+* * *
 
-### 1️⃣ Challenge Initialization
+## 🧩 Framework Usage
 
-- 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.
+### 🅰️ Angular Implementation (Standalone)
 
-### 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:
+The Angular wrapper is now **standalone**. Import it directly into your component’s `imports` array without using a module:
 
-| 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      |
+import { Component } from '@angular/core';  
+import { LivenessComponent } from '@richard.fadiora/liveness-detection/angular';  
+  
+@Component({  
+  selector: 'app-verify',  
+  standalone: true,  
+  imports: \[LivenessComponent\],  
+  template: \`  
+    <LivenessCheck  
+      \[apiUrl\]="'https://api.yoursite.com/verify'"  
+      \[containerClass\]="'my-custom-container'"  
+      \[buttonClass\]="'btn-primary'"  
+      (onComplete)="handleSuccess($event)"  
+      (onError)="handleError($event)">  
+    </LivenessCheck>  
+  \`  
+})  
+export class VerifyComponent {  
+  
+  handleSuccess(result: any) {  
+    console.log("Image Captured:", result.image);  
+  }  
+  
+  handleError(error: any) {  
+    console.error(error.reason);  
+  }  
+  
+}
 
-### 3️⃣ Backend Liveness Verification
+⚠️ **Important Rule:** Standalone components **must not** be declared in an NgModule. Doing so disables standalone behavior and can cause runtime errors.
 
-- 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.
+* * *
 
----
+### ⚛️ React Implementation
 
-## ✅ Success & Failure Behavior
+# 
 
-### Success
-- UI (or custom component) shows success feedback.  
-- `onComplete` callback is triggered:
-```js
-onComplete({ success: true, image: frame, skinConfidence });
-```
+import { LivenessSDK } from "@richard.fadiora/liveness-detection/react";  
+  
+function App() {  
+  return (  
+    <LivenessSDK  
+      apiUrl\="https://api.yoursite.com/verify"  
+      classNames\={{ container: "p-4 bg-dark", video: "rounded-lg" }}  
+      onComplete\={(res) => console.log("Success:", res.image)}  
+      onError\={(err) => console.error(err.reason)}  
+    />  
+  );  
+}
 
-### Failure
-- UI shows failure message.  
-- `onError` callback is triggered:
-```js
-onError({ success: false, reason, skinConfidence: null });
-```
-- Component resets; user must start a new session.
+* * *
 
----
+## 🎨 Prop-Driven Styling
 
-## 📦 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                      |
 
+| Angular Input | React Prop | Description |
+| --- | --- | --- |
+| containerClass | classNames.container | Main wrapper div |
+| videoClass | classNames.webcam | The video element |
+| buttonClass | classNames.button | The Start button |
+| timerClass | classNames.timer | Countdown timer text |
+| instructionBoxClass | classNames.challenge | Challenge instruction box |
+| statusOverlayClass | classNames.overlay | Overlay during verification |
+| errorMessageClass | classNames.error | Wrapper for error messages |
 
----
+* * *
 
-## 🧩 Usage Example
+## ⚙️ Configuration & Thresholds
 
-### 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;
+| Prop Name | Default | Description |
+| --- | --- | --- |
+| duration | 60 | Total session time in seconds |
+| smileThreshold | 0.20 | Minimum width for smile detection |
+| blinkThreshold | 0.01 | Sensitivity for eye-closure detection |
+| minturnHeadThreshold | 0.15 | Minimum yaw for right-turn detection |
+| maxturnHeadThreshold | 0.85 | Maximum yaw for left-turn detection |
+
+* * *
+
+## ✅ Success & Failure Payload
+
+### onComplete Result
+
+# 
+
+{  
+  success: true,  
+  image: string,        // Base64 encoded capture frame  
+  skinConfidence: number // AI model confidence score  
 }
-.liveness-success {
-  color: #4caf50;
-  margin-top: 20px;
+
+### onError Result
+
+# 
+
+{  
+  success: false,  
+  reason: string,       // "timeout", "challenge\_failed", "camera\_denied"
 }
-```
 
----
+* * *
 
-## ⏳ Timeout Rules
+## 🛠️ Advanced: Headless Mode
 
-- Maximum session duration: set via `duration` prop (default 60s).  
-- On timeout: challenge stops, state resets, backend verification is not triggered.
 
----
 
-## 🔐 Security Architecture
+*   **Angular 🅰️**: Inject `LivenessService` to access the `state$` observable.
+    
+*   **React ⚛️**: Use `useLiveness` hook.
+    
 
-- **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.
+Allows full custom UI while using the detection engine.
 
----
+* * *
 
-## 📊 Verification Criteria
+## 🏗️ SDK Architecture
 
-- 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
+Layered design allows the same core detection engine to support multiple frameworks:
 
-- 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
+*   **core**: `LivenessEngine.ts` handles webcam, landmark detection, challenge sequencing, frame capture, and backend verification
+    
+*   **react**: React components + hooks handle UI and state
+    
+*   **angular**: Standalone components + services handle UI and state
+    
 
----
+* * *
 
-## 🚀 Ideal Use Cases
+## 🔧 Integration Notes
 
-- KYC verification flows  
-- Identity onboarding  
-- Account recovery  
-- Secure login  
-- Financial / compliance apps
 
----
+
+*   **MediaPipe Dependency**: If you see `TS2307: Cannot find module '@mediapipe/tasks-vision'`, run `npm install @mediapipe/tasks-vision`.
+    
+*   **Angular Button Logic**: `[disabled]="!canStart"` — Angular inverts the boolean so button is enabled when `canStart = true`.
+    
+*   **Webcam Permissions**: Required.
+    
+*   **Timeout Rules**: Session resets if challenges aren’t completed within the configured duration.
+    
+*   **Backend**: Accepts multiple frames for final spoof analysis. Endpoint must be `/v1/verify`
+    
+*   **CORS**: Ensure API allows requests from your frontend domain.
+    
+
+* * *
 
 ## 👨‍💻 Maintainer
 
-Fadiora Richard.
 
+
+**Fadiora Richard**  
+Maintained by **Princeps Credit Systems Limited**