@hexar/biometric-identity-sdk-core 1.0.0

package/src/types/index.ts

@@ -0,0 +1,380 @@
+/**
+ * Core type definitions for Biometric Identity SDK
+ */
+
+export interface ValidationResult {
+  /** Face match confidence score (0-100) */
+  matchScore: number;
+  
+  /** Whether face from video matches face in document */
+  isValidFaceMatch: boolean;
+  
+  /** Whether document passes authenticity checks */
+  isDocumentAuthentic: boolean;
+  
+  /** Liveness detection confidence score (0-100) */
+  livenessScore: number;
+  
+  /** Extracted data from document OCR */
+  extractedDocumentData: DocumentData;
+  
+  /** List of warnings detected during validation */
+  warnings: string[];
+  
+  /** Timestamp of validation */
+  timestamp: number;
+  
+  /** Detailed breakdown of validation steps */
+  details?: ValidationDetails;
+}
+
+export interface DocumentData {
+  firstName: string;
+  lastName: string;
+  documentNumber: string;
+  dateOfBirth: string;
+  expirationDate: string;
+  nationality: string;
+  documentType?: string;
+  gender?: string;
+  address?: string;
+  issuingCountry?: string;
+  rawText?: string;
+}
+
+export interface ValidationDetails {
+  faceDetection: {
+    detected: boolean;
+    confidence: number;
+    boundingBox?: BoundingBox;
+  };
+  documentQuality: {
+    hasGlare: boolean;
+    hasBlur: boolean;
+    hasCropping: boolean;
+    hasReflections: boolean;
+    edgeDetectionScore: number;
+  };
+  tamperDetection: {
+    isTampered: boolean;
+    tamperScore: number;
+    suspiciousRegions: BoundingBox[];
+  };
+  hologramDetection?: {
+    detected: boolean;
+    confidence: number;
+  };
+  livenessChecks: {
+    passedMotionCheck: boolean;
+    passedTextureCheck: boolean;
+    passedDepthCheck: boolean;
+  };
+}
+
+export interface BoundingBox {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+import { SupportedLanguage } from '../i18n';
+
+export interface BiometricConfig {
+  apiEndpoint?: string;
+  apiKey?: string;
+  language?: SupportedLanguage;
+  enableBackendValidation?: boolean;
+  enableLocalStorage?: boolean;
+  encryptionKey?: string;
+  minMatchScore?: number;
+  minLivenessScore?: number;
+  validationTimeout?: number;
+  modelPaths?: {
+    faceDetection?: string;
+    faceRecognition?: string;
+    livenessDetection?: string;
+  };
+}
+
+export interface ThemeConfig {
+  /** Primary brand color */
+  primaryColor?: string;
+  
+  /** Background color */
+  backgroundColor?: string;
+  
+  /** Text color */
+  textColor?: string;
+  
+  /** Secondary text color */
+  secondaryTextColor?: string;
+  
+  /** Button border radius */
+  buttonRadius?: number;
+  
+  /** Font family */
+  fontFamily?: string;
+  
+  /** Custom logo */
+  logo?: string | any;
+  
+  /** Success color */
+  successColor?: string;
+  
+  /** Error color */
+  errorColor?: string;
+  
+  /** Warning color */
+  warningColor?: string;
+}
+
+export interface VideoLivenessOptions {
+  /** Duration of video recording in milliseconds */
+  duration?: number;
+  
+  /** Instructions for user to follow */
+  instructions?: LivenessInstruction[];
+  
+  /** Frame rate for video capture */
+  frameRate?: number;
+  
+  /** Quality of video (0-1) */
+  quality?: number;
+}
+
+export type LivenessInstruction = 
+  | 'look_left'
+  | 'look_right'
+  | 'look_up'
+  | 'look_down'
+  | 'smile'
+  | 'blink'
+  | 'turn_head_left'
+  | 'turn_head_right';
+
+export interface VideoResult {
+  /** Video frames as base64 encoded images */
+  frames: string[];
+  
+  /** Duration of captured video */
+  duration: number;
+  
+  /** Whether all instructions were followed */
+  instructionsFollowed: boolean;
+  
+  /** Quality score of the video */
+  qualityScore: number;
+  
+  /** List of completed challenge actions (for active liveness) */
+  challengesCompleted?: string[];
+  
+  /** Session ID from backend challenge (if using backend) */
+  sessionId?: string;
+}
+
+export interface ImageData {
+  /** Base64 encoded image data */
+  data: string;
+  
+  /** Image width */
+  width: number;
+  
+  /** Image height */
+  height: number;
+  
+  /** MIME type */
+  mimeType: string;
+  
+  /** File size in bytes */
+  size: number;
+}
+
+export interface EncryptedData {
+  /** Encrypted data payload */
+  data: string;
+  
+  /** Initialization vector */
+  iv: string;
+  
+  /** Authentication tag */
+  tag?: string;
+  
+  /** Encryption algorithm used */
+  algorithm: string;
+}
+
+export interface BiometricError extends Error {
+  code: BiometricErrorCode;
+  details?: any;
+}
+
+export enum BiometricErrorCode {
+  CAMERA_PERMISSION_DENIED = 'CAMERA_PERMISSION_DENIED',
+  CAMERA_NOT_AVAILABLE = 'CAMERA_NOT_AVAILABLE',
+  FACE_NOT_DETECTED = 'FACE_NOT_DETECTED',
+  MULTIPLE_FACES_DETECTED = 'MULTIPLE_FACES_DETECTED',
+  DOCUMENT_NOT_DETECTED = 'DOCUMENT_NOT_DETECTED',
+  POOR_IMAGE_QUALITY = 'POOR_IMAGE_QUALITY',
+  LIVENESS_CHECK_FAILED = 'LIVENESS_CHECK_FAILED',
+  FACE_MATCH_FAILED = 'FACE_MATCH_FAILED',
+  DOCUMENT_TAMPERED = 'DOCUMENT_TAMPERED',
+  OCR_FAILED = 'OCR_FAILED',
+  VALIDATION_TIMEOUT = 'VALIDATION_TIMEOUT',
+  NETWORK_ERROR = 'NETWORK_ERROR',
+  MODEL_LOAD_FAILED = 'MODEL_LOAD_FAILED',
+  ENCRYPTION_FAILED = 'ENCRYPTION_FAILED',
+  UNKNOWN_ERROR = 'UNKNOWN_ERROR',
+}
+
+export interface FaceEmbedding {
+  /** 512-dimensional face embedding vector */
+  vector: number[];
+  
+  /** Confidence score of face detection */
+  confidence: number;
+  
+  /** Bounding box of detected face */
+  boundingBox: BoundingBox;
+}
+
+export interface DocumentValidationResult {
+  /** Whether document is authentic */
+  isAuthentic: boolean;
+  
+  /** Overall authenticity score (0-100) */
+  authenticityScore: number;
+  
+  /** Quality assessment */
+  quality: {
+    hasGlare: boolean;
+    hasBlur: boolean;
+    hasCropping: boolean;
+    hasReflections: boolean;
+    edgeScore: number;
+  };
+  
+  /** Tamper detection results */
+  tamper: {
+    detected: boolean;
+    score: number;
+    regions: BoundingBox[];
+  };
+  
+  /** Hologram detection (if applicable) */
+  hologram?: {
+    detected: boolean;
+    confidence: number;
+  };
+}
+
+export interface LivenessValidationResult {
+  /** Whether liveness check passed */
+  isLive: boolean;
+  
+  /** Overall liveness score (0-100) */
+  livenessScore: number;
+  
+  /** Individual check results */
+  checks: {
+    motionCheck: boolean;
+    textureCheck: boolean;
+    depthCheck: boolean;
+    blinkCheck?: boolean;
+  };
+  
+  /** Detected face in video */
+  faceEmbedding: FaceEmbedding;
+}
+
+export interface SDKState {
+  /** Current step in the flow */
+  currentStep: SDKStep;
+  
+  /** Front ID image */
+  frontID?: ImageData;
+  
+  /** Back ID image */
+  backID?: ImageData;
+  
+  /** Video liveness data */
+  videoData?: VideoResult;
+  
+  /** Validation result */
+  validationResult?: ValidationResult;
+  
+  /** Error state */
+  error?: BiometricError;
+  
+  /** Loading state */
+  isLoading: boolean;
+  
+  /** Progress percentage (0-100) */
+  progress: number;
+}
+
+export enum SDKStep {
+  INIT = 'INIT',
+  CAPTURE_FRONT_ID = 'CAPTURE_FRONT_ID',
+  CAPTURE_BACK_ID = 'CAPTURE_BACK_ID',
+  RECORD_LIVENESS = 'RECORD_LIVENESS',
+  VALIDATING = 'VALIDATING',
+  RESULT = 'RESULT',
+  ERROR = 'ERROR',
+}
+
+export interface ModelConfig {
+  /** Model name */
+  name: string;
+  
+  /** Model path or URL */
+  path: string;
+  
+  /** Model version */
+  version: string;
+  
+  /** Input shape */
+  inputShape: number[];
+  
+  /** Output shape */
+  outputShape: number[];
+}
+
+export interface BackendValidationRequest {
+  /** Encrypted front ID image */
+  frontID: EncryptedData;
+  
+  /** Encrypted back ID image */
+  backID: EncryptedData;
+  
+  /** Encrypted video frames */
+  videoFrames: EncryptedData;
+  
+  /** Local validation result */
+  localValidationResult: ValidationResult;
+  
+  /** SDK version */
+  sdkVersion: string;
+  
+  /** Timestamp */
+  timestamp: number;
+}
+
+export interface BackendValidationResponse {
+  /** Whether validation was approved */
+  approved: boolean;
+  
+  /** Match score from backend */
+  matchScore: number;
+  
+  /** Additional checks performed by backend */
+  additionalChecks?: Record<string, any>;
+  
+  /** Backend validation timestamp */
+  timestamp: number;
+  
+  /** Backend session ID */
+  sessionId: string;
+}
+
+

package/src/validation/DocumentValidator.ts

@@ -0,0 +1,353 @@
+/**
+ * Document Validation - Detect tampering, quality issues, and authenticity
+ */
+
+import { DocumentValidationResult, BoundingBox } from '../types';
+
+export class DocumentValidator {
+  private model: any;
+  private isModelLoaded: boolean = false;
+
+  constructor(private modelPath?: string) {}
+
+  /**
+   * Load document validation models
+   */
+  async loadModel(): Promise<void> {
+    if (this.isModelLoaded) return;
+
+    try {
+      console.log('Loading document validation model...');
+      
+      // Simulate model loading
+      await new Promise(resolve => setTimeout(resolve, 300));
+      
+      this.isModelLoaded = true;
+      console.log('Document validation model loaded successfully');
+    } catch (error) {
+      throw new Error(`Failed to load document validation model: ${error}`);
+    }
+  }
+
+  /**
+   * Validate document authenticity and quality
+   */
+  async validateDocument(imageData: string | Buffer): Promise<DocumentValidationResult> {
+    if (!this.isModelLoaded) {
+      await this.loadModel();
+    }
+
+    try {
+      // Perform parallel quality checks
+      const [qualityResult, tamperResult, hologramResult] = await Promise.all([
+        this.checkQuality(imageData),
+        this.detectTampering(imageData),
+        this.detectHologram(imageData),
+      ]);
+
+      // Calculate overall authenticity score
+      const authenticityScore = this.calculateAuthenticityScore(
+        qualityResult,
+        tamperResult,
+        hologramResult
+      );
+
+      const isAuthentic = authenticityScore >= 70 && !tamperResult.detected;
+
+      return {
+        isAuthentic,
+        authenticityScore,
+        quality: qualityResult,
+        tamper: tamperResult,
+        hologram: hologramResult,
+      };
+    } catch (error) {
+      throw new Error(`Document validation failed: ${error}`);
+    }
+  }
+
+  /**
+   * Check document image quality
+   */
+  private async checkQuality(imageData: string | Buffer): Promise<{
+    hasGlare: boolean;
+    hasBlur: boolean;
+    hasCropping: boolean;
+    hasReflections: boolean;
+    edgeScore: number;
+  }> {
+    // In real implementation:
+    // 1. Detect bright spots (glare)
+    // 2. Calculate blur metric (Laplacian variance)
+    // 3. Detect document edges and check if complete
+    // 4. Detect reflective areas
+
+    const hasGlare = await this.detectGlare(imageData);
+    const hasBlur = await this.detectBlur(imageData);
+    const hasCropping = await this.detectCropping(imageData);
+    const hasReflections = await this.detectReflections(imageData);
+    const edgeScore = await this.calculateEdgeScore(imageData);
+
+    return {
+      hasGlare,
+      hasBlur,
+      hasCropping,
+      hasReflections,
+      edgeScore,
+    };
+  }
+
+  /**
+   * Detect glare in document image
+   */
+  private async detectGlare(imageData: string | Buffer): Promise<boolean> {
+    // In real implementation:
+    // 1. Convert to grayscale
+    // 2. Find pixels above high threshold (> 240)
+    // 3. Calculate percentage of bright pixels
+    // 4. Check if bright regions form patches (glare patterns)
+
+    // Mock implementation
+    const randomScore = Math.random();
+    return randomScore < 0.15; // 15% chance of glare
+  }
+
+  /**
+   * Detect blur in document image
+   */
+  private async detectBlur(imageData: string | Buffer): Promise<boolean> {
+    // In real implementation:
+    // 1. Apply Laplacian operator
+    // 2. Calculate variance of Laplacian
+    // 3. Low variance indicates blur
+
+    // Mock implementation
+    const randomScore = Math.random();
+    return randomScore < 0.10; // 10% chance of blur
+  }
+
+  /**
+   * Detect if document is cropped
+   */
+  private async detectCropping(imageData: string | Buffer): Promise<boolean> {
+    // In real implementation:
+    // 1. Detect document edges using Canny edge detection
+    // 2. Find document contours
+    // 3. Check if all four corners are visible
+
+    // Mock implementation
+    const randomScore = Math.random();
+    return randomScore < 0.08; // 8% chance of cropping
+  }
+
+  /**
+   * Detect reflections on document
+   */
+  private async detectReflections(imageData: string | Buffer): Promise<boolean> {
+    // In real implementation:
+    // 1. Analyze specular highlights
+    // 2. Detect glossy surface patterns
+    // 3. Check for uneven lighting
+
+    // Mock implementation
+    const randomScore = Math.random();
+    return randomScore < 0.12; // 12% chance of reflections
+  }
+
+  /**
+   * Calculate edge detection score
+   */
+  private async calculateEdgeScore(imageData: string | Buffer): Promise<number> {
+    // In real implementation:
+    // 1. Apply Canny edge detection
+    // 2. Calculate edge pixel density
+    // 3. Normalize to 0-100 scale
+
+    // Mock implementation - random score between 70-98
+    return Math.round(70 + Math.random() * 28);
+  }
+
+  /**
+   * Detect document tampering
+   */
+  private async detectTampering(imageData: string | Buffer): Promise<{
+    detected: boolean;
+    score: number;
+    regions: BoundingBox[];
+  }> {
+    // In real implementation:
+    // 1. Error Level Analysis (ELA)
+    // 2. Clone detection
+    // 3. JPEG artifact analysis
+    // 4. Metadata analysis
+    // 5. Font consistency check
+    // 6. Color histogram analysis
+
+    const tamperScore = await this.calculateTamperScore(imageData);
+    const suspiciousRegions = await this.findSuspiciousRegions(imageData);
+
+    return {
+      detected: tamperScore > 60,
+      score: tamperScore,
+      regions: suspiciousRegions,
+    };
+  }
+
+  /**
+   * Calculate tampering score
+   */
+  private async calculateTamperScore(imageData: string | Buffer): Promise<number> {
+    // In real implementation:
+    // 1. Analyze compression artifacts
+    // 2. Check for inconsistent noise patterns
+    // 3. Detect copy-paste regions
+    // 4. Validate text rendering consistency
+
+    // Mock implementation - most documents are authentic
+    const randomScore = Math.random();
+    return randomScore < 0.95 ? Math.round(Math.random() * 30) : Math.round(60 + Math.random() * 40);
+  }
+
+  /**
+   * Find suspicious regions in document
+   */
+  private async findSuspiciousRegions(imageData: string | Buffer): Promise<BoundingBox[]> {
+    // In real implementation:
+    // 1. Apply ELA and find high-error regions
+    // 2. Detect cloned regions
+    // 3. Find inconsistent JPEG blocks
+
+    // Mock implementation - usually no suspicious regions
+    const randomScore = Math.random();
+    if (randomScore < 0.95) {
+      return [];
+    }
+
+    // Return 1-2 suspicious regions
+    return [
+      {
+        x: Math.round(Math.random() * 200),
+        y: Math.round(Math.random() * 100),
+        width: 50 + Math.round(Math.random() * 100),
+        height: 30 + Math.round(Math.random() * 50),
+      },
+    ];
+  }
+
+  /**
+   * Detect hologram on document
+   */
+  private async detectHologram(imageData: string | Buffer): Promise<{
+    detected: boolean;
+    confidence: number;
+  } | undefined> {
+    // In real implementation:
+    // 1. Detect rainbow color patterns
+    // 2. Analyze light reflection patterns
+    // 3. Check for 3D effects
+    // 4. Validate hologram location on document
+
+    // Mock implementation
+    const randomScore = Math.random();
+    
+    if (randomScore > 0.3) {
+      return {
+        detected: true,
+        confidence: 75 + Math.round(Math.random() * 20),
+      };
+    }
+
+    return {
+      detected: false,
+      confidence: Math.round(Math.random() * 50),
+    };
+  }
+
+  /**
+   * Calculate overall authenticity score
+   */
+  private calculateAuthenticityScore(
+    quality: any,
+    tamper: any,
+    hologram: any
+  ): number {
+    let score = 100;
+
+    // Deduct points for quality issues
+    if (quality.hasGlare) score -= 15;
+    if (quality.hasBlur) score -= 20;
+    if (quality.hasCropping) score -= 25;
+    if (quality.hasReflections) score -= 10;
+    
+    // Edge score impact
+    if (quality.edgeScore < 70) score -= 15;
+    else if (quality.edgeScore < 80) score -= 10;
+
+    // Tampering severely impacts score
+    if (tamper.detected) {
+      score -= 40;
+    } else {
+      score -= Math.round(tamper.score * 0.3);
+    }
+
+    // Hologram bonus (if detected and confident)
+    if (hologram?.detected && hologram.confidence > 70) {
+      score = Math.min(100, score + 5);
+    }
+
+    return Math.max(0, Math.round(score));
+  }
+
+  /**
+   * Detect document type (passport, ID card, driver's license, etc.)
+   */
+  async detectDocumentType(imageData: string | Buffer): Promise<string> {
+    // In real implementation:
+    // 1. Use template matching
+    // 2. Detect document layout patterns
+    // 3. OCR specific regions to identify type
+
+    // Mock implementation
+    const types = ['passport', 'national_id', 'drivers_license'];
+    return types[Math.floor(Math.random() * types.length)];
+  }
+
+  /**
+   * Validate document expiration
+   */
+  validateExpiration(expirationDate: string): boolean {
+    try {
+      const expiry = new Date(expirationDate);
+      const now = new Date();
+      return expiry > now;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Clean up resources
+   */
+  dispose(): void {
+    this.model = null;
+    this.isModelLoaded = false;
+  }
+}
+
+/**
+ * Validate document meets minimum quality standards
+ */
+export function meetsQualityStandards(quality: {
+  hasGlare: boolean;
+  hasBlur: boolean;
+  hasCropping: boolean;
+  hasReflections: boolean;
+  edgeScore: number;
+}): boolean {
+  if (quality.hasBlur || quality.hasCropping) return false;
+  if (quality.hasGlare && quality.hasReflections) return false;
+  if (quality.edgeScore < 60) return false;
+  return true;
+}
+
+