@richard.fadiora/liveness-detection 4.3.13 → 5.0.0

package/README.md

@@ -1,427 +1,164 @@
-# Liveness Detection SDK
+# Liveness Detection SDK v5.0.0
 
+A high-security, cross-framework **Liveness Detection SDK** designed for financial services. v5.0.0 introduces **Temporal Identity Locking** to prevent identity switching during the verification process.
 
+## 🔒 New Security Protocols (v5.0.0)
 
-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 🅰️**.
+This version introduces a "Zero-Trust" frontend architecture:
 
-* * *
-
-## 🚀 Key Features in v4.3.13
-
-
-
-*   📦 **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
+*   **Identity Anchoring**: Locks the biometric proportions of the first person detected. If a different person attempts to complete a challenge, the session terminates.
     
-*   📋 Sequential challenge execution (Smile, Blink, Turn\_Head, Thumbs\_Up)
+*   **Continuity Guard**: Monitoring at 60fps to ensure the face never leaves the frame. A "Face Lost" event for >250ms triggers an automatic security reset.
     
-*   🧠 Real-time MediaPipe face & hand landmark detection
+*   **Teleport Detection**: Prevents video injection or photo-swapping by detecting unnatural "jumps" in face coordinates.
     
-*   🛡️ Protection against presentation attacks (photo/video), glare, and replay attacks
+*   **Multi-Tab Lock**: Prevents brute-force attempts by ensuring only one liveness session is active per browser instance.
     
 
-* * *
-
-## 📦 Installation & Imports
-
-
-
-`npm install @richard.fadiora/liveness-detection`
-
-### Import Paths
-
-# 
-
-| 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.
-
 * * *
 
 ## 🧩 Framework Usage
 
 ### 🅰️ Angular Implementation (Standalone)
 
-# 
-
-The Angular wrapper is now **standalone**. Import it directly into your component’s `imports` array without using a module:
-
-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);  
-  }  
-  
-}
-
-⚠️ **Important Rule:** Standalone components **must not** be declared in an NgModule. Doing so disables standalone behavior and can cause runtime errors.
-
-* * *
-
-### ⚛️ React Implementation
-
-# 
-
-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)}  
-    />  
-  );  
-}
-
-* * *
-
-## 🎨 Prop-Driven Styling
-
-
-
-| 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 |
-
-* * *
-## Customizing Challenge Labels
-
-
-
-You can override the default technical strings (e.g., `Thumbs_Up`) with user-friendly text or different languages using the `challengeMapping` input.
-
-| Technical ID | Default Display |
-| --- | --- |
-| `Smile` | "Smile" |
-| `Blink` | "Blink" |
-| `Turn_Head` | "Turn Head" |
-| `Thumbs_Up` | "Thumbs Up" |
-
-**Example: Localization (French)**
-
-TypeScript
-
-    // app.component.ts
-    challengeLabels = {
-      'Smile': 'Souriez',
-      'Blink': 'Clignez des yeux',
-      'Turn_Head': 'Tournez la tête',
-      'Thumbs_Up': 'Levez le pouce'
-    };
-HTML
-
-    <LivenessCheck [challengeMapping]="challengeLabels"></LivenessCheck>
-
-###   
-
-### 📥 Text & Label Customization
-
-### 
-
-Customize all user-facing strings to match your app's tone or language.
-
-| Input Property | Default Value |
-| --- | --- |
-| `successMessage` | "Verification Successful!" |
-| `errorMessage` | "Verification failed. Please try again." |
-| `startButtonLabel` | "Start Verification" |
-| `retryButtonLabel` | "Try Again" |
-
-**Example Usage:**
-
-HTML
-
-    <LivenessCheck
-      [successMessage]="'Identity Confirmed!'"
-      [errorMessage]="'We couldn\'t verify you. Move to a brighter room.'"
-      [startButtonLabel]="'Begin Scan'"
-    >
-    </LivenessCheck>
-
-## 🔄 State Synchronization
-
-### 
-
-The `onStateChange` event provides a real-time stream of the SDK's internal engine. This is useful for building custom instruction overlays or logging telemetry.
-
-### The `LivenessState` Object
-
-### 
-
-When the state changes, the SDK emits an object with the following structure:
-
-| Property | Type | Description |
-| --- | --- | --- |
-| `status` | enum | The current phase of the SDK (see Status Flow below). |
-| `sequence` | Challenge[] | The array of 3 randomized challenges (e.g., ['Smile', 'Blink', 'Turn_Head']). |
-| `currentStep` | number | The index (0-2) of the challenge the user is currently performing. |
-| `timeLeft` | number | The countdown timer in seconds before the session expires. |
-| `isStepTransitioning` | boolean | true during the 1.5s pause after a successful challenge. |
-| `errorMsg` | string | Contains the technical error code (e.g., SPOOF_BLUR_DETECTED) when status is 'error'. |
-
-* * *
-
-### Implementation: Custom Error Mapping
-
-### 
-
-You can use the `onStateChange` handler to "intercept" technical error codes and map them to user-friendly instructions in your local UI.
-
-**Example: Reactive Instructions**
+The Angular wrapper now exposes `snapshots` via the state observable, allowing you to build "Verification Galleries."
 
 TypeScript
 
     // app.component.ts
-    handleStateUpdate(state: LivenessState) {
-      if (state.status === 'error' && state.errorMsg) {
-        
-        // Pattern matching for specific error prefixes
-        switch (true) {
-          case state.errorMsg.startsWith('FACE_'):
-            this.myLocalStatus = "Center your face in the circle";
-            break;
-          case state.errorMsg.startsWith('LIGHT_'):
-            this.myLocalStatus = "Find a brighter spot";
-            break;
-          case state.errorMsg.startsWith('TIMEOUT'):
-            this.myLocalStatus = "Session expired. Tap retry.";
-            break;
-          default:
-            this.myLocalStatus = state.errorMsg;
-        }
+    @Component({
+      selector: 'app-verify',
+      standalone: true,
+      imports: [LivenessComponent],
+      template: `
+        <LivenessCheck
+          [apiUrl]="'https://api.yoursite.com/verify'"
+          (onStateChange)="handleState($event)"
+          (onComplete)="handleSuccess($event)">
+        </LivenessCheck>
+    
+        <div class="snapshot-gallery">
+          @for (snap of currentSnapshots; track snap.timestamp) {
+            <img [src]="snap.image" class="w-20 h-20 rounded border-2 border-green-500" />
+          }
+        </div>
+      `
+    })
+    export class VerifyComponent {
+      currentSnapshots: any[] = [];
+    
+      handleState(state: LivenessState) {
+        this.currentSnapshots = state.snapshots;
       }
-    }
-HTML
-
-    <LivenessCheck 
-      (onStateChange)="handleStateUpdate($event)"
-      [errorMessage]="myLocalStatus">
-    </LivenessCheck>
-
-* * *
-
-### Why use the State Handler?
-
-### 
-
-*   **Decoupled Logic:** You can keep the SDK's UI simple while handling complex business logic (like analytics or redirecting users) in your main app.
     
-*   **Dynamic UI:** Change your app's background color, show a progress bar, or trigger haptic feedback based on the `status` transitions.
-    
-*   **Error Interception:** Translate technical backend codes into the specific "voice" of your brand.
-
-## 🚨 Error Reference Guide
-
-
-
-When the SDK emits a `status: 'error'`, the `errorMsg` will contain one of the following technical codes. You can use these to provide contextual hints (e.g., "Too much light") in your UI.
-
-| Error Code | Meaning | Recommended User Hint |
-| --- | --- | --- |
-| `SCREEN_REFLECTION_DETECTED` | Excessive glare or light bouncing off the screen. | "Move away from direct light or windows." |
-| `SPOOF_BLUR_DETECTED` | Image is too dark or out of focus. | "Ensure your face is well-lit and clear." |
-| `SCREEN_MOIRE_PATTERN_DETECTED` | Digital pixel patterns detected (indicates a photo/screen). | "Please use your physical device camera." |
-| `STATIC_IMAGE_OR_SCREEN` | Natural micro-movements not detected. | "Blink or move slightly during the scan." |
-| `NO_IMAGE_DATA` | Camera permissions denied or stream interrupted. | "Enable camera access in your settings." |
-| `AI_SPOOF_DETECTION` | Low skin-texture confidence from the AI model. | "Verification failed. Please try again." |
-| `Network Error` | The backend API could not be reached. | "Check your internet connection." |
-| `Liveness Check Failed` | Generic fallback for unspecified validation errors. | "Please try again in a different environment." |
+      handleSuccess(result: LivenessSDKResult) {
+        // result.snapshots contains the final proof for your local storage
+      }
+    }
 
 * * *
 
-### Pro-Tip: Implementing a User Hint System
-
-## 
+### ⚛️ React Implementation
 
-Instead of showing the raw code (which might confuse a non-technical user), use the `onStateChange` handler to map these codes to your friendly "Recommended User Hint" column.
+The React wrapper has been updated to provide specific security feedback.
 
 TypeScript
 
-    // Example: Mapping technical codes to friendly messages
-    handleStateUpdate(state: LivenessState) {
-      const errorMap: Record<string, string> = {
-        'SCREEN_REFLECTION_DETECTED': 'Too much light! Please move to a shaded area.',
-        'SPOOF_BLUR_DETECTED': 'It’s a bit dark. Try increasing your screen brightness.',
-        'NO_IMAGE_DATA': 'We can’t see you! Please check your camera permissions.'
-      };
-    
-      if (state.status === 'error') {
-        this.friendlyMessage = errorMap[state.errorMsg] || "Something went wrong. Let's try again.";
-      }
+    import { LivenessSDK } from "@richard.fadiora/liveness-detection/react";
+    
+    function LoanVerification() {
+      return (
+        <LivenessSDK
+          apiUrl="https://api.yoursite.com/verify"
+          onStateChange={(state) => {
+            if (state.status === "error") {
+              console.error("Security Halt:", state.errorMsg);
+            }
+          }}
+          onComplete={(res) => {
+            // res.snapshots includes the 3 challenge-response images
+            submitLoanApplication(res.snapshots);
+          }}
+        />
+      );
     }
 
 * * *
-### 🧩 Type Handling
 
-## 
+## 🛠️ Advanced: Consuming the Headless Core
 
-The SDK emits state updates reactively. During the initialization phase, the state may briefly be `null` or `undefined`. Always use optional chaining when accessing state properties:
+If you are building a custom UI for a high-stakes loan flow, you should consume the `LivenessEngine` directly to have granular control over the security lifecycle.
 
-TypeScript
+### Initializing the Engine
 
-    handleStateUpdate(state: LivenessState | null) {
-      if (state?.status === 'error') {
-        // safely handle error
-      }
-    }
+TypeScript
 
+    import { LivenessEngine } from "@richard.fadiora/liveness-detection";
     
-### 📦 Latest Changes Summary
-
-## 
-
-*   **Zero-CSS Architecture:** All default styles removed; fully styleable via `[ngClass]` inputs.
+    const engine = new LivenessEngine({
+      apiUrl: "...",
+      onStateChange: (state) => updateUI(state),
+    });
     
-*   **Label Mapping:** Added `[challengeMapping]` to allow custom text for "Smile", "Blink", etc.
+    // 1. Load WASM and Models
+    await engine.loadModels();
     
-*   **State Hook:** New `(onStateChange)` event for advanced lifecycle management.
+    // 2. Attach Video Element
+    engine.attachVideo(document.getElementById('my-video'));
     
-*   **Encapsulation:** Set to `ViewEncapsulation.None` for seamless Tailwind and Global CSS integration.
-
-
-## ⚙️ Configuration & Thresholds
-
-
-
-| 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
-
-# 
+    // 3. Start Session (Automatic Lock Check)
+    engine.start();
 
-{  
-  success: true,  
-  image: string,        // Base64 encoded capture frame  
-  skinConfidence: number // AI model confidence score  
-}
+### Security Reset vs. User Retry
 
-### onError Result
-
-# 
-
-{  
-  success: false,  
-  reason: string,       // "timeout", "challenge\_failed", "camera\_denied"
-}
+*   **`engine.reset()`**: Use this when a security violation occurs (e.g., "Identity Mismatch"). It clears the biometric anchors, allowing a new session to begin from scratch.
+    
+*   **`engine.stop()`**: Always call this when the user navigates away from the page to release the **Multi-Tab Lock**.
+    
 
 * * *
 
-## ⚡ Atomic Initialization 
+## 🚨 Updated Error Reference (v4.4.0)
 
-The SDK UI is context-aware; it will not render buttons or instructions until the hardware (Camera) and the software (AI Models) are fully synchronized and ready for capture.
+The following codes are now emitted by the frontend engine **instantly**, without hitting the backend:
 
-## 🛠️ Advanced: Headless Mode
-
-
-
-*   **Angular 🅰️**: Inject `LivenessService` to access the `state$` observable.
-    
-*   **React ⚛️**: Use `useLiveness` hook.
-    
-
-Allows full custom UI while using the detection engine.
+| Error Code | Meaning | Context |
+| --- | --- | --- |
+| Multiple faces detected | Session killed because >1 person is in view. | Prevents "assistance" fraud. |
+| Face lost. Session reset. | Face left the frame for more than 250ms. | Prevents seat-swapping. |
+| Security violation: Identity mismatch. | Biometric ratios shifted significantly mid-session. | Prevents mid-stream person-swapping. |
+| Another session is active. | User has the verification open in another tab. | Prevents multi-device brute forcing. |
 
 * * *
 
-## 🏗️ SDK Architecture
-
+## 🏗️ Architectural Flow
 
+### Data Integrity Note
 
-Layered design allows the same core detection engine to support multiple frameworks:
+The `snapshots` array in the `LivenessState` now contains **Challenge-Verified Snapshots**.
 
-*   **core**: `LivenessEngine.ts` handles webcam, landmark detection, challenge sequencing, frame capture, and backend verification
+1.  **Snapshot 1**: Captured exactly when "Smile" was detected.
     
-*   **react**: React components + hooks handle UI and state
+2.  **Snapshot 2**: Captured exactly when "Blink" was detected.
     
-*   **angular**: Standalone components + services handle UI and state
+3.  **Snapshot 3**: Captured exactly when the third challenge was met.
     
 
-* * *
-
-## 🔧 Integration Notes
+These images are cropped to **224x224px** focusing on the face, making them optimal for backend audit logs while keeping payload sizes minimal.
 
+* * *
 
+## 🔧 Integration Notes for v5.0.0
 
-*   **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`.
+*   **WASM Path**: Ensure your server allows cross-origin requests for the MediaPipe `.wasm` files hosted on JSDelivr.
     
-*   **Webcam Permissions**: Required.
+*   **Memory Management**: If using in a Single Page App (SPA), always call `engine.stop()` in `onDestroy` or `useEffect` cleanup to release the webcam and the session lock.
     
-*   **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.
+*   **Hardware Acceleration**: For the "Identity Lock" to run smoothly at 60fps, browsers must have hardware acceleration enabled.
     
 
 * * *
 
-## 👨‍💻 Maintainer
-
-
+**Maintainer:** Fadiora Richard
 
-**Fadiora Richard**  
-Maintained by **Princeps Credit Systems Limited**
+**Organization:** Princeps Credit Systems Limited