Liveness Detection SDK v5.1.0

A high-security, cross-framework Liveness Detection SDK designed for financial services. v5.1.0 introduces Temporal Identity Locking to prevent identity switching during the verification process.

🔒 New Security Protocols (v5.1.0)

This version introduces a "Zero-Trust" frontend architecture:

• Identity Anchoring: Locks the biometric proportions of the first person detected. If a different person attempts to complete a challenge, the session terminates.

• Continuity Guard: Monitoring at 60fps to ensure the face never leaves the frame. A "Face Lost" event for >250ms triggers an automatic security reset.

• Teleport Detection: Prevents video injection or photo-swapping by detecting unnatural "jumps" in face coordinates.

• Multi-Tab Lock: Prevents brute-force attempts by ensuring only one liveness session is active per browser instance.

🧩 Framework Usage

🅰️ Angular Implementation (Standalone)

The Angular wrapper now exposes snapshots via the state observable, allowing you to build "Verification Galleries."

TypeScript

// app.component.ts
@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;
  }

  handleSuccess(result: LivenessSDKResult) {
    // result.snapshots contains the final proof for your local storage
  }
}

⚛️ React Implementation

The React wrapper has been updated to provide specific security feedback.

TypeScript

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);
      }}
    />
  );
}

🛠️ Advanced: Consuming the Headless Core

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.

Initializing the Engine

TypeScript

import { LivenessEngine } from "@richard.fadiora/liveness-detection";

const engine = new LivenessEngine({
  apiUrl: "...",
  onStateChange: (state) => updateUI(state),
});

// 1. Load WASM and Models
await engine.loadModels();

// 2. Attach Video Element
engine.attachVideo(document.getElementById('my-video'));

// 3. Start Session (Automatic Lock Check)
engine.start();

Security Reset vs. User Retry

• 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.

🚨 Updated Error Reference (v5.1.0)

The following codes are now emitted by the frontend engine instantly, without hitting the backend:

| 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. |

⚠️ Security Warnings & Temporary Interruption

Version 5.0.2 implements a non-fatal warning system for non-critical security events (e.g., fleeting obscuration).

• Temporary Interruption: If a security violation occurs (e.g., face obscured), the LivenessEngine will pause detection for 2 seconds to allow the user to adjust their position.

• Warning Counter: The engine tracks these events using warningCount. If the violations exceed MAX_WARNINGS (default: 3), the session will trigger a failInstantly event.

• State Feedback: During the 2-second pause, the errorMsg property in LivenessState will be populated with a temporary notification (e.g., "Please ensure both ears are fully visible. (Warning 1/3)").

Best Practice: Always subscribe to onStateChange in your UI layer to ensure your user-facing components react to the errorMsg text.

🏗️ Architectural Flow

Data Integrity Note

The snapshots array in the LivenessState now contains Challenge-Verified Snapshots.

1. Snapshot 1: Captured exactly when "Smile" was detected.

2. Snapshot 2: Captured exactly when "Blink" was detected.

3. Snapshot 3: Captured exactly when the third challenge was met.

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.1.0

• WASM Path: Ensure your server allows cross-origin requests for the MediaPipe .wasm files hosted on JSDelivr.

• 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.

• Hardware Acceleration: For the "Identity Lock" to run smoothly at 60fps, browsers must have hardware acceleration enabled.

Maintainer: Fadiora Richard

Organization: Princeps Credit Systems Limited