@hexar/biometric-identity-sdk-core 1.0.0

package/src/ai-models/LivenessDetector.ts

@@ -0,0 +1,274 @@
+/**
+ * Liveness Detection using video analysis
+ * Detects if the subject is a real person vs photo/video replay
+ */
+
+import { LivenessValidationResult, VideoResult, LivenessInstruction } from '../types';
+import { FaceDetector } from './FaceDetector';
+
+export interface LivenessFrame {
+  imageData: string;
+  timestamp: number;
+  instruction?: LivenessInstruction;
+}
+
+export class LivenessDetector {
+  private faceDetector: FaceDetector;
+  private model: any;
+  private isModelLoaded: boolean = false;
+
+  constructor(private modelPath?: string) {
+    this.faceDetector = new FaceDetector();
+  }
+
+  /**
+   * Load the liveness detection model
+   */
+  async loadModel(): Promise<void> {
+    if (this.isModelLoaded) return;
+
+    try {
+      console.log('Loading liveness detection model...');
+      
+      // Load face detector
+      await this.faceDetector.loadModel();
+      
+      // Simulate liveness model loading
+      await new Promise(resolve => setTimeout(resolve, 500));
+      
+      this.isModelLoaded = true;
+      console.log('Liveness detection model loaded successfully');
+    } catch (error) {
+      throw new Error(`Failed to load liveness detection model: ${error}`);
+    }
+  }
+
+  /**
+   * Validate liveness from video frames
+   */
+  async validateLiveness(videoResult: VideoResult): Promise<LivenessValidationResult> {
+    if (!this.isModelLoaded) {
+      await this.loadModel();
+    }
+
+    try {
+      // Extract frames for analysis
+      const frames = videoResult.frames.map((frame, index) => ({
+        imageData: frame,
+        timestamp: (index / videoResult.frames.length) * videoResult.duration,
+      }));
+
+      // Perform multiple liveness checks
+      const motionCheck = await this.checkMotion(frames);
+      const textureCheck = await this.checkTexture(frames);
+      const depthCheck = await this.check3DDepth(frames);
+      const blinkCheck = await this.checkBlink(frames);
+
+      // Get face embedding from best frame
+      const faceEmbedding = await this.extractBestFaceEmbedding(frames);
+
+      // Calculate overall liveness score
+      const livenessScore = this.calculateLivenessScore({
+        motionCheck,
+        textureCheck,
+        depthCheck,
+        blinkCheck,
+      });
+
+      const isLive = livenessScore >= 80 && motionCheck && textureCheck;
+
+      return {
+        isLive,
+        livenessScore,
+        checks: {
+          motionCheck,
+          textureCheck,
+          depthCheck,
+          blinkCheck,
+        },
+        faceEmbedding,
+      };
+    } catch (error) {
+      throw new Error(`Liveness validation failed: ${error}`);
+    }
+  }
+
+  /**
+   * Check for natural motion in video
+   */
+  private async checkMotion(frames: LivenessFrame[]): Promise<boolean> {
+    if (frames.length < 3) return false;
+
+    try {
+      // Detect faces in multiple frames
+      const facePositions = await Promise.all(
+        frames.slice(0, 10).map(async (frame) => {
+          const bbox = await this.faceDetector.getFaceBoundingBox(frame.imageData);
+          return bbox;
+        })
+      );
+
+      // Check if face position changes (indicates real movement)
+      const validPositions = facePositions.filter(pos => pos !== null);
+      
+      if (validPositions.length < 3) return false;
+
+      // Calculate movement variance
+      const xPositions = validPositions.map(pos => pos!.x);
+      const yPositions = validPositions.map(pos => pos!.y);
+
+      const xVariance = this.calculateVariance(xPositions);
+      const yVariance = this.calculateVariance(yPositions);
+
+      // Motion should exist but not be too extreme
+      const hasMotion = (xVariance + yVariance) > 10 && (xVariance + yVariance) < 1000;
+
+      return hasMotion;
+    } catch (error) {
+      console.error('Motion check failed:', error);
+      return false;
+    }
+  }
+
+  /**
+   * Check texture patterns to detect printed photos
+   */
+  private async checkTexture(frames: LivenessFrame[]): Promise<boolean> {
+    // In real implementation:
+    // 1. Analyze high-frequency texture patterns
+    // 2. Detect print artifacts (moiré patterns)
+    // 3. Check for screen refresh patterns
+
+    // Mock implementation - simulate texture analysis
+    const randomScore = Math.random();
+    return randomScore > 0.2; // 80% pass rate for valid faces
+  }
+
+  /**
+   * Check 3D depth using parallax or facial structure
+   */
+  private async check3DDepth(frames: LivenessFrame[]): Promise<boolean> {
+    // In real implementation:
+    // 1. Analyze facial landmarks movement
+    // 2. Check for parallax effect when head moves
+    // 3. Validate 3D structure consistency
+
+    // Mock implementation
+    const randomScore = Math.random();
+    return randomScore > 0.15; // 85% pass rate
+  }
+
+  /**
+   * Detect eye blinks in video
+   */
+  private async checkBlink(frames: LivenessFrame[]): Promise<boolean> {
+    // In real implementation:
+    // 1. Detect eyes in each frame
+    // 2. Calculate eye aspect ratio (EAR)
+    // 3. Detect blink events (EAR drops and recovers)
+
+    // Mock implementation - simulate blink detection
+    const randomScore = Math.random();
+    return randomScore > 0.3; // 70% detection rate
+  }
+
+  /**
+   * Extract face embedding from the best quality frame
+   */
+  private async extractBestFaceEmbedding(frames: LivenessFrame[]) {
+    // Select middle frames for best quality
+    const middleFrames = frames.slice(
+      Math.floor(frames.length * 0.3),
+      Math.floor(frames.length * 0.7)
+    );
+
+    // Get face detections for middle frames
+    const detections = await Promise.all(
+      middleFrames.slice(0, 5).map(frame =>
+        this.faceDetector.detectFaces(frame.imageData)
+      )
+    );
+
+    // Find frame with highest confidence
+    let bestEmbedding = null;
+    let bestConfidence = 0;
+
+    for (const detection of detections) {
+      if (detection.faces.length > 0) {
+        const face = detection.faces[0];
+        if (face.confidence > bestConfidence) {
+          bestConfidence = face.confidence;
+          bestEmbedding = face;
+        }
+      }
+    }
+
+    if (!bestEmbedding) {
+      throw new Error('No face detected in video frames');
+    }
+
+    return bestEmbedding;
+  }
+
+  /**
+   * Calculate overall liveness score
+   */
+  private calculateLivenessScore(checks: {
+    motionCheck: boolean;
+    textureCheck: boolean;
+    depthCheck: boolean;
+    blinkCheck: boolean;
+  }): number {
+    const weights = {
+      motionCheck: 0.35,
+      textureCheck: 0.35,
+      depthCheck: 0.20,
+      blinkCheck: 0.10,
+    };
+
+    let score = 0;
+    
+    if (checks.motionCheck) score += weights.motionCheck * 100;
+    if (checks.textureCheck) score += weights.textureCheck * 100;
+    if (checks.depthCheck) score += weights.depthCheck * 100;
+    if (checks.blinkCheck) score += weights.blinkCheck * 100;
+
+    return Math.round(score);
+  }
+
+  /**
+   * Calculate variance of an array of numbers
+   */
+  private calculateVariance(values: number[]): number {
+    const mean = values.reduce((a, b) => a + b, 0) / values.length;
+    const squaredDiffs = values.map(value => Math.pow(value - mean, 2));
+    return squaredDiffs.reduce((a, b) => a + b, 0) / values.length;
+  }
+
+  /**
+   * Validate instruction following
+   */
+  async validateInstructions(
+    frames: LivenessFrame[],
+    expectedInstructions: LivenessInstruction[]
+  ): Promise<boolean> {
+    // In real implementation:
+    // 1. Detect head pose for each frame
+    // 2. Detect facial expressions (smile, etc.)
+    // 3. Validate instructions were followed in sequence
+
+    // Mock implementation
+    return expectedInstructions.length > 0 && frames.length >= expectedInstructions.length * 10;
+  }
+
+  /**
+   * Clean up resources
+   */
+  dispose(): void {
+    this.faceDetector.dispose();
+    this.model = null;
+    this.isModelLoaded = false;
+  }
+}
+
+

package/src/api/BackendClient.ts

@@ -0,0 +1,395 @@
+/**
+ * Backend API Client for Biometric Identity SDK
+ * Communicates with the Python backend for AI-powered validation
+ */
+
+import { 
+  ValidationResult, 
+  VideoResult, 
+  LivenessValidationResult,
+  DocumentData,
+  BiometricConfig 
+} from '../types';
+
+export interface ChallengeAction {
+  action: string;
+  instruction: string;
+  duration_ms: number;
+  order: number;
+}
+
+export interface ChallengeResponse {
+  success: boolean;
+  session_id: string;
+  challenges: ChallengeAction[];
+  total_duration_ms: number;
+  expires_at: string;
+}
+
+export interface LivenessResponse {
+  success: boolean;
+  is_live: boolean;
+  liveness_score: number;
+  checks: Array<{
+    name: string;
+    passed: boolean;
+    score: number;
+    details?: string;
+  }>;
+  face_detected: boolean;
+  face_count: number;
+  best_frame_index?: number;
+  warnings: string[];
+  session_id?: string;
+}
+
+export interface FaceMatchResponse {
+  success: boolean;
+  is_match: boolean;
+  match_score: number;
+  distance: number;
+  document_face_detected: boolean;
+  live_face_detected: boolean;
+  document_face_confidence: number;
+  live_face_confidence: number;
+  warnings: string[];
+}
+
+export interface DocumentValidationResponse {
+  success: boolean;
+  is_authentic: boolean;
+  authenticity_score: number;
+  document_type_detected?: string;
+  extracted_data: {
+    first_name?: string;
+    last_name?: string;
+    full_name?: string;
+    document_number?: string;
+    date_of_birth?: string;
+    expiration_date?: string;
+    issue_date?: string;
+    nationality?: string;
+    gender?: string;
+    address?: string;
+    issuing_country?: string;
+    document_type?: string;
+    mrz_line_1?: string;
+    mrz_line_2?: string;
+    mrz_line_3?: string;
+    raw_text?: string;
+  };
+  quality: {
+    overall_score: number;
+    has_glare: boolean;
+    has_blur: boolean;
+    has_cropping: boolean;
+    has_shadows: boolean;
+    is_color: boolean;
+    resolution_adequate: boolean;
+    edge_detection_score: number;
+  };
+  tamper_detection: {
+    is_tampered: boolean;
+    tamper_score: number;
+    suspicious_regions: Array<{ x: number; y: number; width: number; height: number }>;
+    details?: string;
+  };
+  face_detected_in_document: boolean;
+  warnings: string[];
+}
+
+export interface FullValidationResponse {
+  success: boolean;
+  is_verified: boolean;
+  verification_score: number;
+  liveness_passed: boolean;
+  face_match_passed: boolean;
+  document_authentic: boolean;
+  match_score: number;
+  liveness_score: number;
+  extracted_data: DocumentValidationResponse['extracted_data'];
+  details: {
+    liveness: LivenessResponse;
+    face_match: FaceMatchResponse;
+    document: DocumentValidationResponse;
+  };
+  warnings: string[];
+  session_id: string;
+  timestamp: string;
+  transaction_id: string;
+}
+
+export interface BackendClientConfig {
+  /** Backend API URL */
+  apiEndpoint: string;
+  /** API key for authentication */
+  apiKey: string;
+  /** Request timeout in ms (default: 60000) */
+  timeout?: number;
+}
+
+/**
+ * Client for communicating with the Biometric Identity Backend
+ */
+export class BackendClient {
+  private config: Required<BackendClientConfig>;
+  private currentSessionId: string | null = null;
+
+  constructor(config: BackendClientConfig) {
+    this.config = {
+      apiEndpoint: config.apiEndpoint.replace(/\/$/, ''), // Remove trailing slash
+      apiKey: config.apiKey,
+      timeout: config.timeout || 60000,
+    };
+  }
+
+  /**
+   * Check if the backend is available
+   */
+  async healthCheck(): Promise<boolean> {
+    try {
+      const response = await this.request<{ status: string }>('/api/v1/health', 'GET');
+      return response.status === 'healthy';
+    } catch (error) {
+      console.warn('Backend health check failed:', error);
+      return false;
+    }
+  }
+
+  /**
+   * Generate a liveness challenge
+   */
+  async generateChallenge(
+    challengeType: 'active' | 'passive' = 'active'
+  ): Promise<ChallengeResponse> {
+    const response = await this.request<ChallengeResponse>(
+      '/api/v1/liveness/challenge',
+      'POST',
+      {
+        challenge_type: challengeType,
+        session_id: this.currentSessionId,
+      }
+    );
+
+    this.currentSessionId = response.session_id;
+    return response;
+  }
+
+  /**
+   * Validate liveness from video frames
+   */
+  async validateLiveness(
+    videoFrames: string[],
+    videoDurationMs: number,
+    challengesCompleted: string[] = [],
+    deviceInfo?: Record<string, any>
+  ): Promise<LivenessResponse> {
+    if (!this.currentSessionId) {
+      throw new Error('No active session. Call generateChallenge() first.');
+    }
+
+    const response = await this.request<LivenessResponse>(
+      '/api/v1/liveness/validate',
+      'POST',
+      {
+        session_id: this.currentSessionId,
+        video_frames: videoFrames,
+        video_duration_ms: videoDurationMs,
+        challenges_completed: challengesCompleted,
+        device_info: deviceInfo,
+      }
+    );
+
+    return response;
+  }
+
+  /**
+   * Compare faces between document and live capture
+   */
+  async matchFaces(
+    documentImage: string,
+    liveFaceImage: string
+  ): Promise<FaceMatchResponse> {
+    return this.request<FaceMatchResponse>(
+      '/api/v1/face/match',
+      'POST',
+      {
+        document_image: documentImage,
+        live_face_image: liveFaceImage,
+        session_id: this.currentSessionId,
+      }
+    );
+  }
+
+  /**
+   * Validate document and extract data
+   */
+  async validateDocument(
+    frontImage: string,
+    backImage?: string,
+    documentType?: string,
+    countryCode?: string
+  ): Promise<DocumentValidationResponse> {
+    return this.request<DocumentValidationResponse>(
+      '/api/v1/document/validate',
+      'POST',
+      {
+        front_image: frontImage,
+        back_image: backImage,
+        document_type: documentType,
+        country_code: countryCode,
+      }
+    );
+  }
+
+  /**
+   * Perform full biometric validation
+   */
+  async fullValidation(params: {
+    frontIdImage: string;
+    backIdImage?: string;
+    videoFrames: string[];
+    videoDurationMs: number;
+    challengesCompleted?: string[];
+    documentType?: string;
+    countryCode?: string;
+    deviceInfo?: Record<string, any>;
+  }): Promise<FullValidationResponse> {
+    if (!this.currentSessionId) {
+      // Generate a challenge first if no session exists
+      await this.generateChallenge();
+    }
+
+    return this.request<FullValidationResponse>(
+      '/api/v1/validate',
+      'POST',
+      {
+        front_id_image: params.frontIdImage,
+        back_id_image: params.backIdImage,
+        video_frames: params.videoFrames,
+        video_duration_ms: params.videoDurationMs,
+        session_id: this.currentSessionId,
+        challenges_completed: params.challengesCompleted || [],
+        document_type: params.documentType,
+        country_code: params.countryCode,
+        device_info: params.deviceInfo,
+      }
+    );
+  }
+
+  /**
+   * Convert backend response to SDK ValidationResult format
+   */
+  convertToValidationResult(response: FullValidationResponse): ValidationResult {
+    const extractedData = response.extracted_data;
+    
+    return {
+      matchScore: response.match_score,
+      isValidFaceMatch: response.face_match_passed,
+      isDocumentAuthentic: response.document_authentic,
+      livenessScore: response.liveness_score * 100, // Convert 0-1 to 0-100
+      extractedDocumentData: {
+        firstName: extractedData.first_name || '',
+        lastName: extractedData.last_name || '',
+        documentNumber: extractedData.document_number || '',
+        dateOfBirth: extractedData.date_of_birth || '',
+        expirationDate: extractedData.expiration_date || '',
+        nationality: extractedData.nationality || '',
+        documentType: extractedData.document_type,
+        gender: extractedData.gender,
+        address: extractedData.address,
+        issuingCountry: extractedData.issuing_country,
+        rawText: extractedData.raw_text,
+      },
+      warnings: response.warnings,
+      timestamp: new Date(response.timestamp).getTime(),
+      details: {
+        faceDetection: {
+          detected: response.details.face_match.live_face_detected,
+          confidence: response.details.face_match.live_face_confidence,
+        },
+        documentQuality: {
+          hasGlare: response.details.document.quality.has_glare,
+          hasBlur: response.details.document.quality.has_blur,
+          hasCropping: response.details.document.quality.has_cropping,
+          hasReflections: response.details.document.quality.has_shadows,
+          edgeDetectionScore: response.details.document.quality.edge_detection_score,
+        },
+        tamperDetection: {
+          isTampered: response.details.document.tamper_detection.is_tampered,
+          tamperScore: response.details.document.tamper_detection.tamper_score,
+          suspiciousRegions: response.details.document.tamper_detection.suspicious_regions,
+        },
+        livenessChecks: {
+          passedMotionCheck: response.details.liveness.checks.find(c => c.name === 'motion_analysis')?.passed || false,
+          passedTextureCheck: response.details.liveness.checks.find(c => c.name === 'texture_analysis')?.passed || false,
+          passedDepthCheck: response.details.liveness.checks.find(c => c.name === 'face_consistency')?.passed || false,
+        },
+      },
+    };
+  }
+
+  /**
+   * Get current session ID
+   */
+  getSessionId(): string | null {
+    return this.currentSessionId;
+  }
+
+  /**
+   * Reset session
+   */
+  resetSession(): void {
+    this.currentSessionId = null;
+  }
+
+  /**
+   * Make HTTP request to backend
+   */
+  private async request<T>(
+    endpoint: string,
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE',
+    body?: any
+  ): Promise<T> {
+    const url = `${this.config.apiEndpoint}${endpoint}`;
+    
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+
+    try {
+      const response = await fetch(url, {
+        method,
+        headers: {
+          'Content-Type': 'application/json',
+          'X-API-Key': this.config.apiKey,
+        },
+        body: body ? JSON.stringify(body) : undefined,
+        signal: controller.signal as RequestInit['signal'],
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({})) as Record<string, any>;
+        throw new Error(
+          errorData?.error?.message || 
+          errorData?.detail ||
+          `Request failed with status ${response.status}`
+        );
+      }
+
+      return await response.json() as T;
+    } catch (error: any) {
+      clearTimeout(timeoutId);
+      
+      if (error.name === 'AbortError') {
+        throw new Error('Request timeout');
+      }
+      
+      throw error;
+    }
+  }
+}
+
+export default BackendClient;
+

package/src/api/index.ts

@@ -0,0 +1,15 @@
+/**
+ * API Client exports
+ */
+
+export { BackendClient } from './BackendClient';
+export type {
+  ChallengeAction,
+  ChallengeResponse,
+  LivenessResponse,
+  FaceMatchResponse,
+  DocumentValidationResponse,
+  FullValidationResponse,
+  BackendClientConfig,
+} from './BackendClient';
+