@hexar/biometric-identity-sdk-core 1.0.0

package/dist/services/BackendValidationService.js

@@ -0,0 +1,174 @@
+"use strict";
+/**
+ * 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)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BackendValidationService = void 0;
+const BackendClient_1 = require("../api/BackendClient");
+class BackendValidationService {
+    constructor(config) {
+        this._isAvailable = false;
+        this.client = new BackendClient_1.BackendClient({
+            apiEndpoint: config.apiEndpoint,
+            apiKey: config.apiKey,
+            timeout: config.timeout || 60000,
+        });
+    }
+    /**
+     * Check if backend is available
+     */
+    async isAvailable() {
+        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) {
+        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, backImage, options) {
+        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, videoFrames, videoDurationMs, challengesCompleted) {
+        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, liveImage) {
+        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) {
+        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() {
+        return this.client.getSessionId();
+    }
+    /**
+     * Reset session
+     */
+    resetSession() {
+        this.client.resetSession();
+    }
+}
+exports.BackendValidationService = BackendValidationService;

package/dist/services/IValidationService.d.ts

@@ -0,0 +1,132 @@
+/**
+ * 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 } 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/dist/services/IValidationService.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Validation Service Interface (Dependency Inversion Principle)
+ *
+ * This interface defines the contract for validation services.
+ * Both local and backend implementations must adhere to this contract.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/services/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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';

package/dist/services/index.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Services Module
+ *
+ * Exports validation service interfaces and implementations
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BackendValidationService = void 0;
+var BackendValidationService_1 = require("./BackendValidationService");
+Object.defineProperty(exports, "BackendValidationService", { enumerable: true, get: function () { return BackendValidationService_1.BackendValidationService; } });

package/dist/types/index.d.ts

@@ -0,0 +1,288 @@
+/**
+ * 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 declare 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 declare 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/dist/types/index.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * Core type definitions for Biometric Identity SDK
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SDKStep = exports.BiometricErrorCode = void 0;
+var BiometricErrorCode;
+(function (BiometricErrorCode) {
+    BiometricErrorCode["CAMERA_PERMISSION_DENIED"] = "CAMERA_PERMISSION_DENIED";
+    BiometricErrorCode["CAMERA_NOT_AVAILABLE"] = "CAMERA_NOT_AVAILABLE";
+    BiometricErrorCode["FACE_NOT_DETECTED"] = "FACE_NOT_DETECTED";
+    BiometricErrorCode["MULTIPLE_FACES_DETECTED"] = "MULTIPLE_FACES_DETECTED";
+    BiometricErrorCode["DOCUMENT_NOT_DETECTED"] = "DOCUMENT_NOT_DETECTED";
+    BiometricErrorCode["POOR_IMAGE_QUALITY"] = "POOR_IMAGE_QUALITY";
+    BiometricErrorCode["LIVENESS_CHECK_FAILED"] = "LIVENESS_CHECK_FAILED";
+    BiometricErrorCode["FACE_MATCH_FAILED"] = "FACE_MATCH_FAILED";
+    BiometricErrorCode["DOCUMENT_TAMPERED"] = "DOCUMENT_TAMPERED";
+    BiometricErrorCode["OCR_FAILED"] = "OCR_FAILED";
+    BiometricErrorCode["VALIDATION_TIMEOUT"] = "VALIDATION_TIMEOUT";
+    BiometricErrorCode["NETWORK_ERROR"] = "NETWORK_ERROR";
+    BiometricErrorCode["MODEL_LOAD_FAILED"] = "MODEL_LOAD_FAILED";
+    BiometricErrorCode["ENCRYPTION_FAILED"] = "ENCRYPTION_FAILED";
+    BiometricErrorCode["UNKNOWN_ERROR"] = "UNKNOWN_ERROR";
+})(BiometricErrorCode || (exports.BiometricErrorCode = BiometricErrorCode = {}));
+var SDKStep;
+(function (SDKStep) {
+    SDKStep["INIT"] = "INIT";
+    SDKStep["CAPTURE_FRONT_ID"] = "CAPTURE_FRONT_ID";
+    SDKStep["CAPTURE_BACK_ID"] = "CAPTURE_BACK_ID";
+    SDKStep["RECORD_LIVENESS"] = "RECORD_LIVENESS";
+    SDKStep["VALIDATING"] = "VALIDATING";
+    SDKStep["RESULT"] = "RESULT";
+    SDKStep["ERROR"] = "ERROR";
+})(SDKStep || (exports.SDKStep = SDKStep = {}));