@hexar/biometric-identity-sdk-core 1.0.0

package/dist/BiometricIdentitySDK.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Main Biometric Identity SDK Class
+ * Initialize once at app start with your API key
+ */
+import { ValidationResult, VideoResult, SDKState } from './types';
+import { ChallengeResponse, ChallengeAction } from './api/BackendClient';
+import { SupportedLanguage } from './i18n';
+export declare class BiometricIdentitySDK {
+    private static instance;
+    private config;
+    private state;
+    private backendClient;
+    private isBackendAvailable;
+    private constructor();
+    /**
+     * Initialize SDK (call once at app start)
+     */
+    static configure(apiKey: string, options?: {
+        language?: SupportedLanguage;
+    }): void;
+    /**
+     * Get SDK instance
+     */
+    static getInstance(): BiometricIdentitySDK;
+    /**
+     * Create a new session (for per-user flows)
+     */
+    static createSession(): BiometricIdentitySDK;
+    /**
+     * Initialize SDK and check backend availability
+     */
+    initialize(): Promise<void>;
+    /**
+     * Generate liveness challenge from backend
+     * Returns challenge actions for the user to perform
+     */
+    generateLivenessChallenge(challengeType?: 'active' | 'passive'): Promise<ChallengeResponse>;
+    /**
+     * Get default challenges for offline mode
+     */
+    getDefaultChallenges(): ChallengeAction[];
+    /**
+     * Get current session ID (from backend)
+     */
+    getSessionId(): string | null;
+    /**
+     * Upload front ID image
+     */
+    uploadFrontID(image: File | Blob | string): Promise<void>;
+    /**
+     * Upload back ID image
+     */
+    uploadBackID(image: File | Blob | string): Promise<void>;
+    /**
+     * Store video recording for liveness detection
+     */
+    storeVideoRecording(videoResult: VideoResult): Promise<void>;
+    /**
+     * Record video for liveness detection (legacy method)
+     */
+    recordVideoLiveness(options?: {
+        duration?: number;
+        instructions?: string[];
+    }): Promise<VideoResult>;
+    /**
+     * Validate identity using all collected data
+     * Uses backend AI for validation
+     */
+    validateIdentity(): Promise<ValidationResult>;
+    /**
+     * Validate using backend API
+     */
+    private validateWithBackend;
+    /**
+     * Process image (convert File/Blob to ImageData)
+     */
+    private processImage;
+    /**
+     * Convert Blob to base64
+     */
+    private blobToBase64;
+    /**
+     * Get current SDK state
+     */
+    getState(): SDKState;
+    /**
+     * Check if backend is available
+     */
+    isUsingBackend(): boolean;
+    /**
+     * Update SDK state
+     */
+    private updateState;
+    /**
+     * Create typed error
+     */
+    private createError;
+    /**
+     * Handle errors
+     */
+    private handleError;
+    /**
+     * Reset SDK state
+     */
+    reset(): void;
+    /**
+     * Clean up resources
+     */
+    dispose(): void;
+}
+export default BiometricIdentitySDK;

package/dist/BiometricIdentitySDK.js

@@ -0,0 +1,395 @@
+"use strict";
+/**
+ * Main Biometric Identity SDK Class
+ * Initialize once at app start with your API key
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BiometricIdentitySDK = void 0;
+const types_1 = require("./types");
+const BackendClient_1 = require("./api/BackendClient");
+const i18n_1 = require("./i18n");
+const API_ENDPOINT = 'https://api.hexar.biometry.com/v1';
+class BiometricIdentitySDK {
+    constructor(config) {
+        this.isBackendAvailable = false;
+        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: types_1.SDKStep.INIT,
+            isLoading: false,
+            progress: 0,
+        };
+        this.backendClient = new BackendClient_1.BackendClient({
+            apiEndpoint: API_ENDPOINT,
+            apiKey: this.config.apiKey,
+            timeout: this.config.validationTimeout,
+        });
+    }
+    /**
+     * Initialize SDK (call once at app start)
+     */
+    static configure(apiKey, options) {
+        if (BiometricIdentitySDK.instance) {
+            console.warn('SDK already initialized');
+            return;
+        }
+        const language = options?.language || 'en';
+        (0, i18n_1.setLanguage)(language);
+        BiometricIdentitySDK.instance = new BiometricIdentitySDK({
+            apiKey,
+            language,
+        });
+    }
+    /**
+     * Get SDK instance
+     */
+    static getInstance() {
+        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() {
+        const config = BiometricIdentitySDK.getInstance().config;
+        return new BiometricIdentitySDK(config);
+    }
+    /**
+     * Initialize SDK and check backend availability
+     */
+    async initialize() {
+        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(types_1.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: types_1.SDKStep.CAPTURE_FRONT_ID
+            });
+            console.log('SDK initialized successfully');
+        }
+        catch (error) {
+            throw this.createError(types_1.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') {
+        if (!this.isBackendAvailable) {
+            throw this.createError(types_1.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(types_1.BiometricErrorCode.NETWORK_ERROR, 'Failed to generate liveness challenge', error);
+        }
+    }
+    /**
+     * Get default challenges for offline mode
+     */
+    getDefaultChallenges() {
+        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() {
+        return this.backendClient?.getSessionId() || null;
+    }
+    /**
+     * Upload front ID image
+     */
+    async uploadFrontID(image) {
+        try {
+            this.updateState({ isLoading: true, currentStep: types_1.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: types_1.SDKStep.CAPTURE_BACK_ID
+            });
+            console.log('Front ID uploaded successfully');
+        }
+        catch (error) {
+            this.handleError(error);
+            throw error;
+        }
+    }
+    /**
+     * Upload back ID image
+     */
+    async uploadBackID(image) {
+        try {
+            this.updateState({ isLoading: true, currentStep: types_1.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: types_1.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) {
+        try {
+            this.updateState({ isLoading: true, currentStep: types_1.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) {
+        try {
+            this.updateState({ isLoading: true, currentStep: types_1.SDKStep.RECORD_LIVENESS });
+            // This would be implemented by the platform-specific wrappers
+            // For now, return a mock result
+            const 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() {
+        try {
+            if (!this.state.frontID || !this.state.videoData) {
+                throw this.createError(types_1.BiometricErrorCode.UNKNOWN_ERROR, 'Missing required data for validation. Need front ID and video.');
+            }
+            if (!this.isBackendAvailable) {
+                throw this.createError(types_1.BiometricErrorCode.NETWORK_ERROR, 'Backend not available. Cannot perform validation.');
+            }
+            this.updateState({
+                isLoading: true,
+                currentStep: types_1.SDKStep.VALIDATING,
+                progress: 75
+            });
+            // Perform backend validation
+            const validationResult = await this.validateWithBackend();
+            this.updateState({
+                validationResult,
+                progress: 100,
+                isLoading: false,
+                currentStep: types_1.SDKStep.RESULT
+            });
+            console.log('Validation completed successfully');
+            return validationResult;
+        }
+        catch (error) {
+            this.handleError(error);
+            throw error;
+        }
+    }
+    /**
+     * Validate using backend API
+     */
+    async validateWithBackend() {
+        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(types_1.BiometricErrorCode.NETWORK_ERROR, 'Backend validation failed', error);
+        }
+    }
+    /**
+     * Process image (convert File/Blob to ImageData)
+     */
+    async processImage(image) {
+        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(types_1.BiometricErrorCode.UNKNOWN_ERROR, 'Failed to process image', error);
+        }
+    }
+    /**
+     * Convert Blob to base64
+     */
+    blobToBase64(blob) {
+        return new Promise((resolve, reject) => {
+            const reader = new FileReader();
+            reader.onloadend = () => {
+                const base64 = reader.result;
+                resolve(base64.split(',')[1] || base64);
+            };
+            reader.onerror = reject;
+            reader.readAsDataURL(blob);
+        });
+    }
+    /**
+     * Get current SDK state
+     */
+    getState() {
+        return { ...this.state };
+    }
+    /**
+     * Check if backend is available
+     */
+    isUsingBackend() {
+        return this.isBackendAvailable;
+    }
+    /**
+     * Update SDK state
+     */
+    updateState(updates) {
+        this.state = {
+            ...this.state,
+            ...updates,
+        };
+    }
+    /**
+     * Create typed error
+     */
+    createError(code, message, details) {
+        const error = new Error(message);
+        error.code = code;
+        error.details = details;
+        return error;
+    }
+    /**
+     * Handle errors
+     */
+    handleError(error) {
+        this.updateState({
+            error: error,
+            isLoading: false,
+            currentStep: types_1.SDKStep.ERROR,
+        });
+    }
+    /**
+     * Reset SDK state
+     */
+    reset() {
+        this.state = {
+            currentStep: types_1.SDKStep.INIT,
+            isLoading: false,
+            progress: 0,
+        };
+        // Reset backend session
+        this.backendClient?.resetSession();
+    }
+    /**
+     * Clean up resources
+     */
+    dispose() {
+        // No local resources to clean up
+        console.log('SDK disposed');
+    }
+}
+exports.BiometricIdentitySDK = BiometricIdentitySDK;
+BiometricIdentitySDK.instance = null;
+exports.default = BiometricIdentitySDK;

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

@@ -0,0 +1,59 @@
+/**
+ * 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 declare class FaceDetector {
+    private modelPath?;
+    private model;
+    private isModelLoaded;
+    constructor(modelPath?: string | undefined);
+    /**
+     * Load the face detection model
+     */
+    loadModel(): Promise<void>;
+    /**
+     * Detect faces in an image
+     */
+    detectFaces(imageData: string | Buffer): Promise<FaceDetectionResult>;
+    /**
+     * Preprocess image for model input
+     */
+    private preprocessImage;
+    /**
+     * Run model inference
+     */
+    private runInference;
+    /**
+     * Post-process detection results
+     */
+    private postprocessDetections;
+    /**
+     * Extract face feature vector
+     */
+    private extractFeatureVector;
+    /**
+     * Check if image contains exactly one face
+     */
+    validateSingleFace(imageData: string | Buffer): Promise<boolean>;
+    /**
+     * Get face bounding box from image
+     */
+    getFaceBoundingBox(imageData: string | Buffer): Promise<BoundingBox | null>;
+    /**
+     * Clean up resources
+     */
+    dispose(): void;
+}
+/**
+ * Calculate Euclidean distance between two face embeddings
+ */
+export declare function calculateFaceDistance(embedding1: number[], embedding2: number[]): number;
+/**
+ * Calculate face similarity score (0-100)
+ */
+export declare function calculateFaceSimilarity(embedding1: number[], embedding2: number[]): number;