@hexar/biometric-identity-sdk-core 1.0.0

package/dist/ai-models/FaceDetector.js

@@ -0,0 +1,167 @@
+"use strict";
+/**
+ * Face Detection using AI models
+ * Uses BlazeFace model for lightweight, fast face detection
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FaceDetector = void 0;
+exports.calculateFaceDistance = calculateFaceDistance;
+exports.calculateFaceSimilarity = calculateFaceSimilarity;
+class FaceDetector {
+    constructor(modelPath) {
+        this.modelPath = modelPath;
+        this.isModelLoaded = false;
+    }
+    /**
+     * Load the face detection model
+     */
+    async loadModel() {
+        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) {
+        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
+     */
+    async preprocessImage(imageData) {
+        // 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
+     */
+    async runInference(tensor) {
+        // 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
+     */
+    postprocessDetections(detections) {
+        return detections.map(detection => ({
+            vector: this.extractFeatureVector(detection),
+            confidence: detection.confidence,
+            boundingBox: detection.boundingBox,
+        }));
+    }
+    /**
+     * Extract face feature vector
+     */
+    extractFeatureVector(detection) {
+        // 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) {
+        const result = await this.detectFaces(imageData);
+        return result.faces.length === 1;
+    }
+    /**
+     * Get face bounding box from image
+     */
+    async getFaceBoundingBox(imageData) {
+        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() {
+        this.model = null;
+        this.isModelLoaded = false;
+    }
+}
+exports.FaceDetector = FaceDetector;
+/**
+ * Calculate Euclidean distance between two face embeddings
+ */
+function calculateFaceDistance(embedding1, embedding2) {
+    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)
+ */
+function calculateFaceSimilarity(embedding1, embedding2) {
+    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);
+}

package/dist/ai-models/LivenessDetector.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Liveness Detection using video analysis
+ * Detects if the subject is a real person vs photo/video replay
+ */
+import { LivenessValidationResult, VideoResult, LivenessInstruction } from '../types';
+export interface LivenessFrame {
+    imageData: string;
+    timestamp: number;
+    instruction?: LivenessInstruction;
+}
+export declare class LivenessDetector {
+    private modelPath?;
+    private faceDetector;
+    private model;
+    private isModelLoaded;
+    constructor(modelPath?: string | undefined);
+    /**
+     * Load the liveness detection model
+     */
+    loadModel(): Promise<void>;
+    /**
+     * Validate liveness from video frames
+     */
+    validateLiveness(videoResult: VideoResult): Promise<LivenessValidationResult>;
+    /**
+     * Check for natural motion in video
+     */
+    private checkMotion;
+    /**
+     * Check texture patterns to detect printed photos
+     */
+    private checkTexture;
+    /**
+     * Check 3D depth using parallax or facial structure
+     */
+    private check3DDepth;
+    /**
+     * Detect eye blinks in video
+     */
+    private checkBlink;
+    /**
+     * Extract face embedding from the best quality frame
+     */
+    private extractBestFaceEmbedding;
+    /**
+     * Calculate overall liveness score
+     */
+    private calculateLivenessScore;
+    /**
+     * Calculate variance of an array of numbers
+     */
+    private calculateVariance;
+    /**
+     * Validate instruction following
+     */
+    validateInstructions(frames: LivenessFrame[], expectedInstructions: LivenessInstruction[]): Promise<boolean>;
+    /**
+     * Clean up resources
+     */
+    dispose(): void;
+}

package/dist/ai-models/LivenessDetector.js

@@ -0,0 +1,218 @@
+"use strict";
+/**
+ * Liveness Detection using video analysis
+ * Detects if the subject is a real person vs photo/video replay
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LivenessDetector = void 0;
+const FaceDetector_1 = require("./FaceDetector");
+class LivenessDetector {
+    constructor(modelPath) {
+        this.modelPath = modelPath;
+        this.isModelLoaded = false;
+        this.faceDetector = new FaceDetector_1.FaceDetector();
+    }
+    /**
+     * Load the liveness detection model
+     */
+    async loadModel() {
+        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) {
+        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
+     */
+    async checkMotion(frames) {
+        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
+     */
+    async checkTexture(frames) {
+        // 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
+     */
+    async check3DDepth(frames) {
+        // 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
+     */
+    async checkBlink(frames) {
+        // 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
+     */
+    async extractBestFaceEmbedding(frames) {
+        // 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
+     */
+    calculateLivenessScore(checks) {
+        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
+     */
+    calculateVariance(values) {
+        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, expectedInstructions) {
+        // 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() {
+        this.faceDetector.dispose();
+        this.model = null;
+        this.isModelLoaded = false;
+    }
+}
+exports.LivenessDetector = LivenessDetector;

package/dist/api/BackendClient.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Backend API Client for Biometric Identity SDK
+ * Communicates with the Python backend for AI-powered validation
+ */
+import { ValidationResult } 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 declare class BackendClient {
+    private config;
+    private currentSessionId;
+    constructor(config: BackendClientConfig);
+    /**
+     * Check if the backend is available
+     */
+    healthCheck(): Promise<boolean>;
+    /**
+     * Generate a liveness challenge
+     */
+    generateChallenge(challengeType?: 'active' | 'passive'): Promise<ChallengeResponse>;
+    /**
+     * Validate liveness from video frames
+     */
+    validateLiveness(videoFrames: string[], videoDurationMs: number, challengesCompleted?: string[], deviceInfo?: Record<string, any>): Promise<LivenessResponse>;
+    /**
+     * Compare faces between document and live capture
+     */
+    matchFaces(documentImage: string, liveFaceImage: string): Promise<FaceMatchResponse>;
+    /**
+     * Validate document and extract data
+     */
+    validateDocument(frontImage: string, backImage?: string, documentType?: string, countryCode?: string): Promise<DocumentValidationResponse>;
+    /**
+     * Perform full biometric validation
+     */
+    fullValidation(params: {
+        frontIdImage: string;
+        backIdImage?: string;
+        videoFrames: string[];
+        videoDurationMs: number;
+        challengesCompleted?: string[];
+        documentType?: string;
+        countryCode?: string;
+        deviceInfo?: Record<string, any>;
+    }): Promise<FullValidationResponse>;
+    /**
+     * Convert backend response to SDK ValidationResult format
+     */
+    convertToValidationResult(response: FullValidationResponse): ValidationResult;
+    /**
+     * Get current session ID
+     */
+    getSessionId(): string | null;
+    /**
+     * Reset session
+     */
+    resetSession(): void;
+    /**
+     * Make HTTP request to backend
+     */
+    private request;
+}
+export default BackendClient;