@hexar/biometric-identity-sdk-core 1.0.0

package/src/i18n/types.ts

@@ -0,0 +1,121 @@
+export type SupportedLanguage = 'en' | 'es' | 'es-AR' | 'pt-BR';
+
+export interface LanguageStrings {
+  common: {
+    loading: string;
+    error: string;
+    retry: string;
+    cancel: string;
+    continue: string;
+    close: string;
+    done: string;
+  };
+  
+  initialization: {
+    initializing: string;
+    connectingToServer: string;
+    loadingModels: string;
+  };
+  
+  instructions: {
+    title: string;
+    subtitle: string;
+    step1: string;
+    step2: string;
+    step3: string;
+    startButton: string;
+    requirements: {
+      goodLighting: string;
+      clearDocument: string;
+      stableHand: string;
+      followInstructions: string;
+    };
+  };
+  
+  capture: {
+    frontId: {
+      title: string;
+      instruction: string;
+      button: string;
+    };
+    backId: {
+      title: string;
+      instruction: string;
+      button: string;
+    };
+    selfie: {
+      title: string;
+      instruction: string;
+      button: string;
+    };
+  };
+  
+  liveness: {
+    title: string;
+    preparing: string;
+    instructions: {
+      lookLeft: string;
+      lookRight: string;
+      lookUp: string;
+      lookDown: string;
+      smile: string;
+      blink: string;
+      turnHeadLeft: string;
+      turnHeadRight: string;
+      stayStill: string;
+    };
+    recording: string;
+    processing: string;
+  };
+  
+  validation: {
+    title: string;
+    validating: string;
+    checkingDocument: string;
+    checkingLiveness: string;
+    matchingFaces: string;
+    almostDone: string;
+  };
+  
+  result: {
+    success: {
+      title: string;
+      message: string;
+      verificationComplete: string;
+    };
+    failure: {
+      title: string;
+      message: string;
+      tryAgain: string;
+    };
+  };
+  
+  errors: {
+    cameraPermissionDenied: string;
+    cameraNotAvailable: string;
+    faceNotDetected: string;
+    multipleFacesDetected: string;
+    documentNotDetected: string;
+    poorImageQuality: string;
+    livenessCheckFailed: string;
+    faceMatchFailed: string;
+    documentTampered: string;
+    networkError: string;
+    timeout: string;
+    unknownError: string;
+  };
+  
+  badges: {
+    secureVerification: string;
+    aiPowered: string;
+    verified: string;
+  };
+  
+  steps: {
+    frontId: string;
+    backId: string;
+    faceVideo: string;
+    validation: string;
+  };
+}
+

package/src/index.ts

@@ -0,0 +1,54 @@
+/**
+ * Biometric Identity SDK - Core Package
+ * Main entry point for the SDK
+ */
+
+// Main SDK class
+export { BiometricIdentitySDK } from './BiometricIdentitySDK';
+export { default } from './BiometricIdentitySDK';
+
+// Type definitions
+export * from './types';
+
+// AI Models
+export { FaceDetector, calculateFaceSimilarity, calculateFaceDistance } from './ai-models/FaceDetector';
+export { LivenessDetector } from './ai-models/LivenessDetector';
+
+// Validation
+export { DocumentValidator, meetsQualityStandards } from './validation/DocumentValidator';
+export { OCREngine, cleanText, isValidDate } from './validation/OCREngine';
+
+// Encryption
+export { EncryptionService, encryptImages, createIntegritySignature } from './encryption';
+
+// Backend API Client
+export { BackendClient } from './api/BackendClient';
+export type { 
+  ChallengeAction,
+  ChallengeResponse,
+  LivenessResponse as BackendLivenessResponse,
+  FaceMatchResponse,
+  DocumentValidationResponse as BackendDocumentResponse,
+  FullValidationResponse,
+  BackendClientConfig,
+} from './api/BackendClient';
+
+// Validation Services (Clean Architecture)
+export { BackendValidationService } from './services/BackendValidationService';
+export type { BackendValidationServiceConfig } from './services/BackendValidationService';
+export type {
+  IValidationService,
+  LivenessChallenge,
+  DocumentValidationResult,
+  LivenessResult,
+  FaceMatchResult,
+} from './services/IValidationService';
+
+// Internationalization
+export { getStrings, setLanguage, getCurrentLanguage } from './i18n';
+export type { SupportedLanguage, LanguageStrings } from './i18n';
+
+// Version
+export const SDK_VERSION = '1.0.0';
+
+

package/src/services/BackendValidationService.ts

@@ -0,0 +1,228 @@
+/**
+ * Backend Validation Service
+ * 
+ * Implements IValidationService using the Python backend API.
+ * This is the recommended service for production use.
+ * 
+ * SOLID Principles Applied:
+ * - Single Responsibility: Only handles backend API communication
+ * - Open/Closed: Implements interface, can be extended without modification
+ * - Liskov Substitution: Can replace any IValidationService implementation
+ * - Interface Segregation: Uses focused IValidationService interface
+ * - Dependency Inversion: Depends on abstractions (IValidationService)
+ */
+
+import {
+  IValidationService,
+  LivenessChallenge,
+  DocumentValidationResult,
+  LivenessResult,
+  FaceMatchResult,
+} from './IValidationService';
+import { ValidationResult } from '../types';
+import { BackendClient } from '../api/BackendClient';
+
+export interface BackendValidationServiceConfig {
+  apiEndpoint: string;
+  apiKey: string;
+  timeout?: number;
+}
+
+export class BackendValidationService implements IValidationService {
+  private client: BackendClient;
+  private _isAvailable: boolean = false;
+
+  constructor(config: BackendValidationServiceConfig) {
+    this.client = new BackendClient({
+      apiEndpoint: config.apiEndpoint,
+      apiKey: config.apiKey,
+      timeout: config.timeout || 60000,
+    });
+  }
+
+  /**
+   * Check if backend is available
+   */
+  async isAvailable(): Promise<boolean> {
+    try {
+      this._isAvailable = await this.client.healthCheck();
+      return this._isAvailable;
+    } catch (error) {
+      this._isAvailable = false;
+      return false;
+    }
+  }
+
+  /**
+   * Generate liveness challenge from backend
+   * 
+   * API Endpoint: POST /api/v1/liveness/challenge
+   */
+  async generateLivenessChallenge(type: 'active' | 'passive'): Promise<LivenessChallenge> {
+    const response = await this.client.generateChallenge(type);
+    
+    return {
+      sessionId: response.session_id,
+      challenges: response.challenges.map(c => ({
+        action: c.action,
+        instruction: c.instruction,
+        durationMs: c.duration_ms,
+        order: c.order,
+      })),
+      totalDurationMs: response.total_duration_ms,
+      expiresAt: new Date(response.expires_at),
+    };
+  }
+
+  /**
+   * Validate document using backend
+   * 
+   * API Endpoint: POST /api/v1/document/validate
+   */
+  async validateDocument(
+    frontImage: string,
+    backImage?: string,
+    options?: { documentType?: string; countryCode?: string }
+  ): Promise<DocumentValidationResult> {
+    const response = await this.client.validateDocument(
+      frontImage,
+      backImage,
+      options?.documentType,
+      options?.countryCode
+    );
+
+    return {
+      isAuthentic: response.is_authentic,
+      authenticityScore: response.authenticity_score,
+      documentTypeDetected: response.document_type_detected,
+      extractedData: {
+        firstName: response.extracted_data.first_name || '',
+        lastName: response.extracted_data.last_name || '',
+        documentNumber: response.extracted_data.document_number || '',
+        dateOfBirth: response.extracted_data.date_of_birth || '',
+        expirationDate: response.extracted_data.expiration_date || '',
+        nationality: response.extracted_data.nationality || '',
+        documentType: response.extracted_data.document_type,
+        gender: response.extracted_data.gender,
+        address: response.extracted_data.address,
+        issuingCountry: response.extracted_data.issuing_country,
+        rawText: response.extracted_data.raw_text,
+      },
+      quality: {
+        overallScore: response.quality.overall_score,
+        hasGlare: response.quality.has_glare,
+        hasBlur: response.quality.has_blur,
+        hasCropping: response.quality.has_cropping,
+        hasShadows: response.quality.has_shadows,
+      },
+      tamperDetection: {
+        isTampered: response.tamper_detection.is_tampered,
+        tamperScore: response.tamper_detection.tamper_score,
+        suspiciousRegions: response.tamper_detection.suspicious_regions,
+      },
+      faceDetectedInDocument: response.face_detected_in_document,
+      warnings: response.warnings,
+    };
+  }
+
+  /**
+   * Validate liveness from video frames
+   * 
+   * API Endpoint: POST /api/v1/liveness/validate
+   */
+  async validateLiveness(
+    sessionId: string,
+    videoFrames: string[],
+    videoDurationMs: number,
+    challengesCompleted: string[]
+  ): Promise<LivenessResult> {
+    const response = await this.client.validateLiveness(
+      videoFrames,
+      videoDurationMs,
+      challengesCompleted
+    );
+
+    return {
+      isLive: response.is_live,
+      livenessScore: response.liveness_score,
+      checks: response.checks.map(c => ({
+        name: c.name,
+        passed: c.passed,
+        score: c.score,
+        details: c.details,
+      })),
+      faceDetected: response.face_detected,
+      faceCount: response.face_count,
+      bestFrameIndex: response.best_frame_index,
+      warnings: response.warnings,
+    };
+  }
+
+  /**
+   * Compare faces between document and live capture
+   * 
+   * API Endpoint: POST /api/v1/face/match
+   */
+  async matchFaces(documentImage: string, liveImage: string): Promise<FaceMatchResult> {
+    const response = await this.client.matchFaces(documentImage, liveImage);
+
+    return {
+      isMatch: response.is_match,
+      matchScore: response.match_score,
+      distance: response.distance,
+      documentFaceDetected: response.document_face_detected,
+      liveFaceDetected: response.live_face_detected,
+      documentFaceConfidence: response.document_face_confidence,
+      liveFaceConfidence: response.live_face_confidence,
+      warnings: response.warnings,
+    };
+  }
+
+  /**
+   * Perform full biometric validation
+   * 
+   * API Endpoint: POST /api/v1/validate
+   * 
+   * This is the main validation endpoint that combines:
+   * 1. Document validation
+   * 2. Liveness detection
+   * 3. Face matching
+   */
+  async fullValidation(params: {
+    frontIdImage: string;
+    backIdImage?: string;
+    videoFrames: string[];
+    videoDurationMs: number;
+    sessionId: string;
+    challengesCompleted: string[];
+    documentType?: string;
+    countryCode?: string;
+  }): Promise<ValidationResult> {
+    const response = await this.client.fullValidation({
+      frontIdImage: params.frontIdImage,
+      backIdImage: params.backIdImage,
+      videoFrames: params.videoFrames,
+      videoDurationMs: params.videoDurationMs,
+      challengesCompleted: params.challengesCompleted,
+      documentType: params.documentType,
+      countryCode: params.countryCode,
+    });
+
+    return this.client.convertToValidationResult(response);
+  }
+
+  /**
+   * Get current session ID
+   */
+  getSessionId(): string | null {
+    return this.client.getSessionId();
+  }
+
+  /**
+   * Reset session
+   */
+  resetSession(): void {
+    this.client.resetSession();
+  }
+}
+

package/src/services/IValidationService.ts

@@ -0,0 +1,158 @@
+/**
+ * Validation Service Interface (Dependency Inversion Principle)
+ * 
+ * This interface defines the contract for validation services.
+ * Both local and backend implementations must adhere to this contract.
+ */
+
+import {
+  ValidationResult,
+  DocumentData,
+  LivenessValidationResult,
+  FaceEmbedding,
+} from '../types';
+
+/**
+ * Liveness Challenge definition
+ */
+export interface LivenessChallenge {
+  sessionId: string;
+  challenges: Array<{
+    action: string;
+    instruction: string;
+    durationMs: number;
+    order: number;
+  }>;
+  totalDurationMs: number;
+  expiresAt: Date;
+}
+
+/**
+ * Document validation result from service
+ */
+export interface DocumentValidationResult {
+  isAuthentic: boolean;
+  authenticityScore: number;
+  documentTypeDetected?: string;
+  extractedData: DocumentData;
+  quality: {
+    overallScore: number;
+    hasGlare: boolean;
+    hasBlur: boolean;
+    hasCropping: boolean;
+    hasShadows: boolean;
+  };
+  tamperDetection: {
+    isTampered: boolean;
+    tamperScore: number;
+    suspiciousRegions: Array<{ x: number; y: number; width: number; height: number }>;
+  };
+  faceDetectedInDocument: boolean;
+  warnings: string[];
+}
+
+/**
+ * Liveness validation result from service
+ */
+export interface LivenessResult {
+  isLive: boolean;
+  livenessScore: number;
+  checks: Array<{
+    name: string;
+    passed: boolean;
+    score: number;
+    details?: string;
+  }>;
+  faceDetected: boolean;
+  faceCount: number;
+  bestFrameIndex?: number;
+  warnings: string[];
+}
+
+/**
+ * Face match result from service
+ */
+export interface FaceMatchResult {
+  isMatch: boolean;
+  matchScore: number;
+  distance: number;
+  documentFaceDetected: boolean;
+  liveFaceDetected: boolean;
+  documentFaceConfidence: number;
+  liveFaceConfidence: number;
+  warnings: string[];
+}
+
+/**
+ * Validation Service Interface
+ * 
+ * Implementations:
+ * - BackendValidationService: Uses Python backend API
+ * - LocalValidationService: Uses local AI models (fallback)
+ */
+export interface IValidationService {
+  /**
+   * Check if the service is available
+   */
+  isAvailable(): Promise<boolean>;
+
+  /**
+   * Generate a liveness challenge for the user
+   */
+  generateLivenessChallenge(type: 'active' | 'passive'): Promise<LivenessChallenge>;
+
+  /**
+   * Validate document authenticity and extract data
+   */
+  validateDocument(
+    frontImage: string,
+    backImage?: string,
+    options?: {
+      documentType?: string;
+      countryCode?: string;
+    }
+  ): Promise<DocumentValidationResult>;
+
+  /**
+   * Validate liveness from video frames
+   */
+  validateLiveness(
+    sessionId: string,
+    videoFrames: string[],
+    videoDurationMs: number,
+    challengesCompleted: string[]
+  ): Promise<LivenessResult>;
+
+  /**
+   * Compare faces between document and live capture
+   */
+  matchFaces(
+    documentImage: string,
+    liveImage: string
+  ): Promise<FaceMatchResult>;
+
+  /**
+   * Perform full biometric validation in one call
+   */
+  fullValidation(params: {
+    frontIdImage: string;
+    backIdImage?: string;
+    videoFrames: string[];
+    videoDurationMs: number;
+    sessionId: string;
+    challengesCompleted: string[];
+    documentType?: string;
+    countryCode?: string;
+  }): Promise<ValidationResult>;
+
+  /**
+   * Get current session ID
+   */
+  getSessionId(): string | null;
+
+  /**
+   * Reset session state
+   */
+  resetSession(): void;
+}
+

package/src/services/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Services Module
+ * 
+ * Exports validation service interfaces and implementations
+ */
+
+export type {
+  IValidationService,
+  LivenessChallenge,
+  DocumentValidationResult,
+  LivenessResult,
+  FaceMatchResult,
+} from './IValidationService';
+
+export { BackendValidationService } from './BackendValidationService';
+export type { BackendValidationServiceConfig } from './BackendValidationService';
+