@hexar/biometric-identity-sdk-core 1.0.0

package/src/BiometricIdentitySDK.ts

@@ -0,0 +1,493 @@
+/**
+ * Main Biometric Identity SDK Class
+ * Initialize once at app start with your API key
+ */
+
+import {
+  ValidationResult,
+  BiometricConfig,
+  VideoResult,
+  ImageData,
+  BiometricError,
+  BiometricErrorCode,
+  SDKState,
+  SDKStep,
+} from './types';
+import { BackendClient, ChallengeResponse, ChallengeAction } from './api/BackendClient';
+import { setLanguage, SupportedLanguage } from './i18n';
+
+const API_ENDPOINT = 'https://api.hexar.biometry.com/v1';
+
+export class BiometricIdentitySDK {
+  private static instance: BiometricIdentitySDK | null = null;
+  private config: Required<BiometricConfig>;
+  private state: SDKState;
+  private backendClient: BackendClient;
+  private isBackendAvailable: boolean = false;
+
+  private constructor(config: BiometricConfig) {
+    if (!config.apiKey) {
+      throw new Error('BiometricIdentitySDK requires an API key');
+    }
+
+    this.config = {
+      apiEndpoint: API_ENDPOINT,
+      apiKey: config.apiKey,
+      language: config.language || 'en',
+      enableBackendValidation: true,
+      enableLocalStorage: config.enableLocalStorage || false,
+      encryptionKey: config.encryptionKey || '',
+      minMatchScore: config.minMatchScore || 85,
+      minLivenessScore: config.minLivenessScore || 80,
+      validationTimeout: config.validationTimeout || 60000,
+      modelPaths: {},
+    };
+
+    this.state = {
+      currentStep: SDKStep.INIT,
+      isLoading: false,
+      progress: 0,
+    };
+
+    this.backendClient = new BackendClient({
+      apiEndpoint: API_ENDPOINT,
+      apiKey: this.config.apiKey,
+      timeout: this.config.validationTimeout,
+    });
+  }
+
+  /**
+   * Initialize SDK (call once at app start)
+   */
+  static configure(apiKey: string, options?: { language?: SupportedLanguage }): void {
+    if (BiometricIdentitySDK.instance) {
+      console.warn('SDK already initialized');
+      return;
+    }
+
+    const language = options?.language || 'en';
+    setLanguage(language);
+
+    BiometricIdentitySDK.instance = new BiometricIdentitySDK({
+      apiKey,
+      language,
+    });
+  }
+
+  /**
+   * Get SDK instance
+   */
+  static getInstance(): BiometricIdentitySDK {
+    if (!BiometricIdentitySDK.instance) {
+      throw new Error('SDK not initialized. Call BiometricIdentitySDK.configure() first');
+    }
+    return BiometricIdentitySDK.instance;
+  }
+
+  /**
+   * Create a new session (for per-user flows)
+   */
+  static createSession(): BiometricIdentitySDK {
+    const config = BiometricIdentitySDK.getInstance().config;
+    return new BiometricIdentitySDK(config);
+  }
+
+  /**
+   * Initialize SDK and check backend availability
+   */
+  async initialize(): Promise<void> {
+    try {
+      console.log('Initializing Biometric Identity SDK...');
+      this.updateState({ isLoading: true, progress: 0 });
+
+      // Check backend availability
+      console.log('Checking backend availability...');
+      this.isBackendAvailable = await this.backendClient.healthCheck();
+      
+      if (!this.isBackendAvailable) {
+        throw this.createError(
+          BiometricErrorCode.NETWORK_ERROR,
+          'Backend server is not available. Please check your API endpoint configuration and try again.'
+        );
+      }
+
+      console.log('✓ Backend is available - ready for validation');
+
+      this.updateState({ 
+        isLoading: false, 
+        progress: 0,
+        currentStep: SDKStep.CAPTURE_FRONT_ID 
+      });
+      
+      console.log('SDK initialized successfully');
+    } catch (error) {
+      throw this.createError(
+        BiometricErrorCode.MODEL_LOAD_FAILED,
+        'Failed to initialize SDK: Backend not available',
+        error
+      );
+    }
+  }
+
+  /**
+   * Generate liveness challenge from backend
+   * Returns challenge actions for the user to perform
+   */
+  async generateLivenessChallenge(
+    challengeType: 'active' | 'passive' = 'active'
+  ): Promise<ChallengeResponse> {
+    if (!this.isBackendAvailable) {
+      throw this.createError(
+        BiometricErrorCode.NETWORK_ERROR,
+        'Backend not available. Cannot generate challenge.'
+      );
+    }
+
+    try {
+      const challenge = await this.backendClient.generateChallenge(challengeType);
+      console.log(`Generated challenge with ${challenge.challenges.length} actions`);
+      return challenge;
+    } catch (error) {
+      throw this.createError(
+        BiometricErrorCode.NETWORK_ERROR,
+        'Failed to generate liveness challenge',
+        error
+      );
+    }
+  }
+
+  /**
+   * Get default challenges for offline mode
+   */
+  getDefaultChallenges(): ChallengeAction[] {
+    return [
+      {
+        action: 'look_left',
+        instruction: 'Slowly turn your head to the LEFT',
+        duration_ms: 2500,
+        order: 1,
+      },
+      {
+        action: 'look_right',
+        instruction: 'Slowly turn your head to the RIGHT',
+        duration_ms: 2500,
+        order: 2,
+      },
+      {
+        action: 'blink',
+        instruction: 'Blink your eyes naturally',
+        duration_ms: 2000,
+        order: 3,
+      },
+    ];
+  }
+
+  /**
+   * Get current session ID (from backend)
+   */
+  getSessionId(): string | null {
+    return this.backendClient?.getSessionId() || null;
+  }
+
+  /**
+   * Upload front ID image
+   */
+  async uploadFrontID(image: File | Blob | string): Promise<void> {
+    try {
+      this.updateState({ isLoading: true, currentStep: SDKStep.CAPTURE_FRONT_ID });
+
+      const imageData = await this.processImage(image);
+      
+      // Store the image - validation happens at the end
+      this.updateState({ 
+        frontID: imageData,
+        progress: 25,
+        isLoading: false,
+        currentStep: SDKStep.CAPTURE_BACK_ID
+      });
+
+      console.log('Front ID uploaded successfully');
+    } catch (error) {
+      this.handleError(error);
+      throw error;
+    }
+  }
+
+  /**
+   * Upload back ID image
+   */
+  async uploadBackID(image: File | Blob | string): Promise<void> {
+    try {
+      this.updateState({ isLoading: true, currentStep: SDKStep.CAPTURE_BACK_ID });
+
+      const imageData = await this.processImage(image);
+      
+      // Store the image - validation happens at the end
+      this.updateState({ 
+        backID: imageData,
+        progress: 50,
+        isLoading: false,
+        currentStep: SDKStep.RECORD_LIVENESS
+      });
+
+      console.log('Back ID uploaded successfully');
+    } catch (error) {
+      this.handleError(error);
+      throw error;
+    }
+  }
+
+  /**
+   * Store video recording for liveness detection
+   */
+  async storeVideoRecording(videoResult: VideoResult): Promise<void> {
+    try {
+      this.updateState({ isLoading: true, currentStep: SDKStep.RECORD_LIVENESS });
+
+      this.updateState({ 
+        videoData: videoResult,
+        progress: 75,
+        isLoading: false,
+      });
+
+      console.log('Video recording stored successfully');
+    } catch (error) {
+      this.handleError(error);
+      throw error;
+    }
+  }
+
+  /**
+   * Record video for liveness detection (legacy method)
+   */
+  async recordVideoLiveness(options?: {
+    duration?: number;
+    instructions?: string[];
+  }): Promise<VideoResult> {
+    try {
+      this.updateState({ isLoading: true, currentStep: SDKStep.RECORD_LIVENESS });
+
+      // This would be implemented by the platform-specific wrappers
+      // For now, return a mock result
+      const videoResult: VideoResult = {
+        frames: [],
+        duration: options?.duration || 8000,
+        instructionsFollowed: true,
+        qualityScore: 85,
+      };
+
+      this.updateState({ 
+        videoData: videoResult,
+        progress: 75,
+        isLoading: false,
+      });
+
+      console.log('Video liveness recorded successfully');
+      return videoResult;
+    } catch (error) {
+      this.handleError(error);
+      throw error;
+    }
+  }
+
+  /**
+   * Validate identity using all collected data
+   * Uses backend AI for validation
+   */
+  async validateIdentity(): Promise<ValidationResult> {
+    try {
+      if (!this.state.frontID || !this.state.videoData) {
+        throw this.createError(
+          BiometricErrorCode.UNKNOWN_ERROR,
+          'Missing required data for validation. Need front ID and video.'
+        );
+      }
+
+      if (!this.isBackendAvailable) {
+        throw this.createError(
+          BiometricErrorCode.NETWORK_ERROR,
+          'Backend not available. Cannot perform validation.'
+        );
+      }
+
+      this.updateState({ 
+        isLoading: true, 
+        currentStep: SDKStep.VALIDATING,
+        progress: 75 
+      });
+
+      // Perform backend validation
+      const validationResult = await this.validateWithBackend();
+
+      this.updateState({ 
+        validationResult,
+        progress: 100,
+        isLoading: false,
+        currentStep: SDKStep.RESULT
+      });
+
+      console.log('Validation completed successfully');
+      return validationResult;
+
+    } catch (error) {
+      this.handleError(error);
+      throw error;
+    }
+  }
+
+  /**
+   * Validate using backend API
+   */
+  private async validateWithBackend(): Promise<ValidationResult> {
+    if (!this.state.frontID || !this.state.videoData) {
+      throw new Error('Required data not available');
+    }
+
+    console.log('Validating with backend API...');
+    this.updateState({ progress: 80 });
+
+    try {
+      const response = await this.backendClient.fullValidation({
+        frontIdImage: this.state.frontID.data,
+        backIdImage: this.state.backID?.data,
+        videoFrames: this.state.videoData.frames,
+        videoDurationMs: this.state.videoData.duration,
+        challengesCompleted: this.state.videoData.challengesCompleted || [],
+      });
+
+      this.updateState({ progress: 95 });
+
+      // Convert backend response to SDK format
+      return this.backendClient.convertToValidationResult(response);
+    } catch (error) {
+      throw this.createError(
+        BiometricErrorCode.NETWORK_ERROR,
+        'Backend validation failed',
+        error
+      );
+    }
+  }
+
+  /**
+   * Process image (convert File/Blob to ImageData)
+   */
+  private async processImage(image: File | Blob | string): Promise<ImageData> {
+    try {
+      if (typeof image === 'string') {
+        // Already base64
+        return {
+          data: image,
+          width: 0,
+          height: 0,
+          mimeType: 'image/jpeg',
+          size: image.length,
+        };
+      }
+
+      // Convert Blob/File to base64
+      const base64 = await this.blobToBase64(image);
+      
+      return {
+        data: base64,
+        width: 0, // Would be set after image analysis
+        height: 0,
+        mimeType: image.type,
+        size: image.size,
+      };
+    } catch (error) {
+      throw this.createError(
+        BiometricErrorCode.UNKNOWN_ERROR,
+        'Failed to process image',
+        error
+      );
+    }
+  }
+
+  /**
+   * Convert Blob to base64
+   */
+  private blobToBase64(blob: Blob): Promise<string> {
+    return new Promise((resolve, reject) => {
+      const reader = new FileReader();
+      reader.onloadend = () => {
+        const base64 = reader.result as string;
+        resolve(base64.split(',')[1] || base64);
+      };
+      reader.onerror = reject;
+      reader.readAsDataURL(blob);
+    });
+  }
+
+  /**
+   * Get current SDK state
+   */
+  getState(): SDKState {
+    return { ...this.state };
+  }
+
+  /**
+   * Check if backend is available
+   */
+  isUsingBackend(): boolean {
+    return this.isBackendAvailable;
+  }
+
+  /**
+   * Update SDK state
+   */
+  private updateState(updates: Partial<SDKState>): void {
+    this.state = {
+      ...this.state,
+      ...updates,
+    };
+  }
+
+  /**
+   * Create typed error
+   */
+  private createError(
+    code: BiometricErrorCode,
+    message: string,
+    details?: any
+  ): BiometricError {
+    const error = new Error(message) as BiometricError;
+    error.code = code;
+    error.details = details;
+    return error;
+  }
+
+  /**
+   * Handle errors
+   */
+  private handleError(error: any): void {
+    this.updateState({
+      error: error as BiometricError,
+      isLoading: false,
+      currentStep: SDKStep.ERROR,
+    });
+  }
+
+  /**
+   * Reset SDK state
+   */
+  reset(): void {
+    this.state = {
+      currentStep: SDKStep.INIT,
+      isLoading: false,
+      progress: 0,
+    };
+    
+    // Reset backend session
+    this.backendClient?.resetSession();
+  }
+
+  /**
+   * Clean up resources
+   */
+  dispose(): void {
+    // No local resources to clean up
+    console.log('SDK disposed');
+  }
+}
+
+export default BiometricIdentitySDK;

package/src/ai-models/FaceDetector.ts

@@ -0,0 +1,200 @@
+/**
+ * Face Detection using AI models
+ * Uses BlazeFace model for lightweight, fast face detection
+ */
+
+import { FaceEmbedding, BoundingBox } from '../types';
+
+export interface FaceDetectionResult {
+  faces: FaceEmbedding[];
+  processingTime: number;
+}
+
+export class FaceDetector {
+  private model: any;
+  private isModelLoaded: boolean = false;
+
+  constructor(private modelPath?: string) {}
+
+  /**
+   * Load the face detection model
+   */
+  async loadModel(): Promise<void> {
+    if (this.isModelLoaded) return;
+
+    try {
+      // In a real implementation, this would load the actual ONNX model
+      // For now, we'll create a mock implementation
+      console.log('Loading face detection model...');
+      
+      // Simulate model loading
+      await new Promise(resolve => setTimeout(resolve, 500));
+      
+      this.isModelLoaded = true;
+      console.log('Face detection model loaded successfully');
+    } catch (error) {
+      throw new Error(`Failed to load face detection model: ${error}`);
+    }
+  }
+
+  /**
+   * Detect faces in an image
+   */
+  async detectFaces(imageData: string | Buffer): Promise<FaceDetectionResult> {
+    if (!this.isModelLoaded) {
+      await this.loadModel();
+    }
+
+    const startTime = Date.now();
+
+    try {
+      // Convert image data to tensor
+      const tensor = await this.preprocessImage(imageData);
+
+      // Run inference
+      const detections = await this.runInference(tensor);
+
+      // Post-process results
+      const faces = this.postprocessDetections(detections);
+
+      const processingTime = Date.now() - startTime;
+
+      return {
+        faces,
+        processingTime,
+      };
+    } catch (error) {
+      throw new Error(`Face detection failed: ${error}`);
+    }
+  }
+
+  /**
+   * Preprocess image for model input
+   */
+  private async preprocessImage(imageData: string | Buffer): Promise<any> {
+    // In real implementation:
+    // 1. Decode image
+    // 2. Resize to model input size (e.g., 128x128)
+    // 3. Normalize pixel values
+    // 4. Convert to tensor
+
+    // Mock implementation
+    return {
+      width: 128,
+      height: 128,
+      data: new Float32Array(128 * 128 * 3),
+    };
+  }
+
+  /**
+   * Run model inference
+   */
+  private async runInference(tensor: any): Promise<any> {
+    // In real implementation, this would use ONNX Runtime
+    // to run the actual face detection model
+
+    // Mock implementation - simulate detection
+    return [
+      {
+        boundingBox: { x: 50, y: 50, width: 100, height: 120 },
+        confidence: 0.95,
+        landmarks: [
+          { x: 75, y: 80 },  // left eye
+          { x: 125, y: 80 }, // right eye
+          { x: 100, y: 110 }, // nose
+          { x: 85, y: 140 },  // left mouth
+          { x: 115, y: 140 }, // right mouth
+        ],
+      },
+    ];
+  }
+
+  /**
+   * Post-process detection results
+   */
+  private postprocessDetections(detections: any[]): FaceEmbedding[] {
+    return detections.map(detection => ({
+      vector: this.extractFeatureVector(detection),
+      confidence: detection.confidence,
+      boundingBox: detection.boundingBox,
+    }));
+  }
+
+  /**
+   * Extract face feature vector
+   */
+  private extractFeatureVector(detection: any): number[] {
+    // In real implementation, this would extract a 512-dim embedding
+    // from a face recognition model (e.g., MobileFaceNet, FaceNet)
+
+    // Mock implementation - generate random 512-dim vector
+    return Array.from({ length: 512 }, () => Math.random() * 2 - 1);
+  }
+
+  /**
+   * Check if image contains exactly one face
+   */
+  async validateSingleFace(imageData: string | Buffer): Promise<boolean> {
+    const result = await this.detectFaces(imageData);
+    return result.faces.length === 1;
+  }
+
+  /**
+   * Get face bounding box from image
+   */
+  async getFaceBoundingBox(imageData: string | Buffer): Promise<BoundingBox | null> {
+    const result = await this.detectFaces(imageData);
+    
+    if (result.faces.length === 0) {
+      return null;
+    }
+
+    // Return the face with highest confidence
+    const bestFace = result.faces.reduce((prev, current) =>
+      current.confidence > prev.confidence ? current : prev
+    );
+
+    return bestFace.boundingBox;
+  }
+
+  /**
+   * Clean up resources
+   */
+  dispose(): void {
+    this.model = null;
+    this.isModelLoaded = false;
+  }
+}
+
+/**
+ * Calculate Euclidean distance between two face embeddings
+ */
+export function calculateFaceDistance(embedding1: number[], embedding2: number[]): number {
+  if (embedding1.length !== embedding2.length) {
+    throw new Error('Embeddings must have the same length');
+  }
+
+  let sum = 0;
+  for (let i = 0; i < embedding1.length; i++) {
+    const diff = embedding1[i] - embedding2[i];
+    sum += diff * diff;
+  }
+
+  return Math.sqrt(sum);
+}
+
+/**
+ * Calculate face similarity score (0-100)
+ */
+export function calculateFaceSimilarity(embedding1: number[], embedding2: number[]): number {
+  const distance = calculateFaceDistance(embedding1, embedding2);
+  
+  // Convert distance to similarity score
+  // Typical face recognition threshold is around 0.6
+  // We map 0.0 distance to 100, and 1.2+ distance to 0
+  const similarity = Math.max(0, Math.min(100, (1.2 - distance) * 83.33));
+  
+  return Math.round(similarity);
+}
+
+