@naniteninja/liveness-verification

Angular library for liveness verification with pose detection and multi-backend support.

Features

• 40+ Predefined Poses: Face expressions, head movements, hand gestures, and combined poses
• Multi-Backend Support: Amazon Rekognition, FaceTec, OpenPose, Azure, and Mock backends
• Configurable: Extensive configuration options for customization
• Standalone Components: Works with Angular 14+ standalone components
• Observable API: RxJS-based API for reactive programming
• Ionic Integration: Built-in Ionic components for mobile-first UI

Installation

npm install @naniteninja/liveness-verification

Peer Dependencies

npm install @angular/common @angular/core @angular/forms @ionic/angular rxjs

Quick Start

Module-based Usage

import { LivenessVerificationModule } from '@naniteninja/liveness-verification';

@NgModule({
  imports: [
    LivenessVerificationModule.forRoot({
      apiUrl: 'https://api.example.com',
      backends: ['amazon', 'facetec'],
      maxRetries: 3
    })
  ]
})
export class AppModule {}

Standalone Usage

import { provideLivenessVerification } from '@naniteninja/liveness-verification';

bootstrapApplication(AppComponent, {
  providers: [
    provideLivenessVerification({
      apiUrl: 'https://api.example.com',
      backends: ['mock']
    })
  ]
});

Template Usage

<facecog-liveness-verification
  [pose]="5"
  (verificationComplete)="onComplete($event)"
  (verificationError)="onError($event)">
</facecog-liveness-verification>

Library Structure

src/lib/
├── models/
│   ├── types/                              # Type definitions (one per file)
│   │   ├── liveness-backend.type.ts
│   │   ├── verification-flow-step.type.ts
│   │   ├── liveness-action.type.ts
│   │   ├── pose-category.type.ts
│   │   ├── pose-difficulty.type.ts
│   │   ├── detection-strategy.type.ts
│   │   └── index.ts
│   │
│   ├── interfaces/                         # Interface definitions (one per file)
│   │   ├── liveness-verification-config.interface.ts
│   │   ├── verification-step-change-event.interface.ts
│   │   ├── verification-progress-event.interface.ts
│   │   ├── liveness-result.interface.ts
│   │   ├── pose-definition.interface.ts
│   │   ├── ... (14 more interfaces)
│   │   └── index.ts
│   │
│   ├── constants/                          # Constant values
│   │   ├── default-liveness-config.constant.ts
│   │   ├── liveness-verification-config.token.ts
│   │   ├── pose-definitions.constant.ts
│   │   ├── category-info.constant.ts
│   │   └── index.ts
│   │
│   ├── utils/                              # Utility functions
│   │   ├── pose.utils.ts
│   │   └── index.ts
│   │
│   └── index.ts                            # Barrel export
│
├── services/
│   ├── backends/
│   │   ├── backend-adapter.interface.ts
│   │   └── mock-backend.service.ts
│   ├── camera.service.ts
│   ├── liveness-config.service.ts
│   ├── pose-selection.service.ts
│   ├── video-recorder.service.ts
│   └── index.ts
│
├── liveness-verification.component.ts
├── liveness-verification.module.ts
└── public-api.ts

Types

import { 
  LivenessBackend,        // 'amazon' | 'openpose' | 'facetec' | 'azure' | 'mock'
  VerificationFlowStep,   // 'intro' | 'permission' | 'preview' | 'facetec' | 'processing' | 'result'
  LivenessAction,         // 'blink' | 'smile' | 'turn-left' | ... (26 actions)
  PoseCategory,           // 'face' | 'head' | 'hand' | 'gesture' | 'combined'
  PoseDifficulty,         // 'easy' | 'medium' | 'hard'
  DetectionStrategy       // 'face-api' | 'openpose' | 'combined'
} from '@naniteninja/liveness-verification';

Interfaces

import {
  LivenessVerificationConfig,   // Main configuration interface
  LivenessResult,               // Verification result
  PoseDefinition,               // Pose definition
  VerificationStepChangeEvent,  // Step change event
  VerificationProgressEvent,    // Progress event
  BackendResponse,              // Backend response
  // ... and more
} from '@naniteninja/liveness-verification';

Constants

import {
  DEFAULT_LIVENESS_CONFIG,       // Default configuration object
  LIVENESS_VERIFICATION_CONFIG,  // Injection token
  POSE_DEFINITIONS,              // Array of 40 poses
  CATEGORY_INFO                  // Category display info
} from '@naniteninja/liveness-verification';

Utility Functions

import {
  getPoseById,          // Get pose by ID (1-40)
  getPosesByCategory,   // Filter poses by category
  getPosesByDifficulty  // Filter poses by difficulty
} from '@naniteninja/liveness-verification';

Services

PoseSelectionService

import { PoseSelectionService } from '@naniteninja/liveness-verification';

@Component({ ... })
export class MyComponent {
  constructor(private poseSelection: PoseSelectionService) {}

  selectPose(id: number) {
    this.poseSelection.selectPose(id);
  }

  getRandomPose() {
    return this.poseSelection.getRandomPose();
  }
}

LivenessConfigService

import { LivenessConfigService } from '@naniteninja/liveness-verification';

@Component({ ... })
export class MyComponent {
  constructor(private configService: LivenessConfigService) {}

  updateConfig() {
    this.configService.updateConfig({
      maxRetries: 5,
      similarityThreshold: 0.7
    });
  }
}

Configuration Options

| Property | Type | Default | Description | |----------|------|---------|-------------| | apiUrl | string | 'http://localhost:3002' | Backend API URL | | backends | LivenessBackend[] | ['mock'] | Backends to use | | poseId | number | undefined | Predefined pose ID (1-40) | | maxRetries | number | 3 | Maximum retry attempts | | autoCapture | boolean | true | Auto-capture when pose matches | | enableVideoRecording | boolean | true | Record video | | similarityThreshold | number | 0.62 | Pose matching threshold |

Available Poses

Face Expressions (1-6)

Face Straight, Blink Once, Blink Twice, Open Mouth, Smile, Raise Eyebrows

Head Movements (7-14)

Turn Left, Turn Right, Look Up, Look Down, Tilt Left, Tilt Right, Nod, Shake Head

Eye & Face Tracking (15-20)

Follow Dot, Wink, Move Closer, Speak Phrase, Rotate Face, Center Face

Hand Gestures (21-29)

Right Palm, Left Palm, Wave Right, Thumbs Up (R/L), OK Sign, Peace Sign, Three Fingers, Five Fingers

Combined Poses (30-40)

Touch Nose, Touch Chin, Touch Cheek (R/L), Cover Eye, Cover Mouth, Frame Face, Cross Arms, Clap, Point

Events

interface LivenessResult {
  success: boolean;
  confidence: number;
  verifiedImage: string;
  videoBlob?: Blob;
  metadata: LivenessMetadata;
  error?: string;
}

interface VerificationStepChangeEvent {
  step: VerificationFlowStep;
  previousStep?: VerificationFlowStep;
  timestamp: Date;
}

interface VerificationProgressEvent {
  step: VerificationFlowStep;
  progress: number; // 0-100
  message: string;
}

Push Notification Integration

import { PoseSelectionService, LivenessConfigService } from '@naniteninja/liveness-verification';

@Component({ ... })
export class AppComponent {
  showVerification = false;

  constructor(
    private poseSelection: PoseSelectionService,
    private configService: LivenessConfigService
  ) {
    this.pushService.onNotification.subscribe(notification => {
      if (notification.type === 'verification_required') {
        this.poseSelection.selectPose(notification.poseId);
        this.configService.updateConfig({ showIntroScreen: false });
        this.showVerification = true;
      }
    });
  }

  onComplete(result: LivenessResult) {
    this.showVerification = false;
    if (result.success) {
      this.sendToBackend(result);
    }
  }
}

License

MIT