@verifiedonchain-protocol/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,563 @@
+import Human, { FaceResult } from '@vladmandic/human';
+import { FaceLandmarker } from '@mediapipe/tasks-vision';
+import React from 'react';
+
+interface RawFacialData {
+    faceEmbedding: number[];
+    faceMesh: number[][];
+    faceLandmarks: number[][];
+    faceRotation: {
+        angle: {
+            yaw: number;
+            pitch: number;
+            roll: number;
+        };
+        matrix: number[];
+    } | null;
+    faceBox: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+    emotion?: Array<{
+        emotion: string;
+        score: number;
+    }>;
+    timestamp: number;
+}
+interface LivenessData {
+    blinkCount: number;
+    blinkTimestamps: number[];
+    emotionTransitions: Array<{
+        from: string;
+        to: string;
+        timestamp: number;
+        duration: number;
+    }>;
+    headMovement: {
+        yawRange: [number, number];
+        pitchRange: [number, number];
+        rollRange: [number, number];
+    };
+    verificationDuration: number;
+    stepCompletionTimes: {
+        happy: number;
+        eyeBlink: number;
+    };
+}
+interface VerificationResult {
+    rawFacialData: RawFacialData;
+    livenessData: LivenessData;
+    isComplete: boolean;
+    message: string;
+}
+interface AleoEmbeddingChunks {
+    embedding_chunk1: number[][];
+    embedding_chunk2: number[][];
+    embedding_chunk3: number[][];
+    embedding_chunk4: number[][];
+}
+interface AleoCircuitInputs extends AleoEmbeddingChunks {
+    liveness_combined: number;
+}
+/**
+ * Clean biometric data payload
+ */
+interface BiometricSimHashPayload {
+    simhash_full: string;
+    liveness_combined: number;
+}
+interface AleoCircuitInputsComplete extends AleoCircuitInputs {
+    salt: string;
+}
+interface DataQuality {
+    isValid: boolean;
+    score: number;
+    issues: string[];
+}
+/**
+ * Average multiple embeddings to reduce noise (Robust outlier rejection)
+ * We calculate the median of all embeddings to find a stable center point,
+ * then filter out frames that are too far from this center, and average the rest.
+ */
+declare function averageEmbeddings(embeddings: number[][]): number[];
+/**
+ * Extract raw facial data from Human.js face detection result
+ * Improved with better error handling and data validation
+ */
+declare function extractRawFacialData(face: FaceResult): RawFacialData;
+/**
+ * Normalize face embedding vector to unit length (L2 normalization)
+ */
+declare function normalizeEmbedding(embedding: number[]): number[];
+/**
+ * Create liveness data from verification session
+ */
+declare function createLivenessData(blinkCount: number, blinkTimestamps: number[], emotionTransitions: LivenessData['emotionTransitions'], headMovement: LivenessData['headMovement'], verificationDuration: number, stepCompletionTimes: LivenessData['stepCompletionTimes']): LivenessData;
+declare class EmbeddingQuantizer {
+    private DEFAULT_MIN;
+    private DEFAULT_MAX;
+    private readonly EPSILON;
+    constructor(calibrationParams?: {
+        min?: number;
+        max?: number;
+    });
+    /**
+     * Quantize embedding to u8 format for Aleo circuit
+     */
+    quantizeEmbedding(embedding: number[] | Float32Array, targetRows?: number, targetCols?: number): number[][];
+    /**
+     * Normalize to [0, 1] range with improved outlier handling
+     */
+    private normalizeToRange;
+    /**
+     * Strategic sampling with information-preserving bias
+     */
+    private reshapeEmbedding;
+    /**
+     * Improved sampling with better distribution
+     */
+    private sampleAndReshape;
+    /**
+     * Pad with mean value to maintain distribution
+     */
+    private padAndReshape;
+    /**
+     * Process embedding for all 4 Aleo circuit chunks
+     */
+    processForAleo(embedding: number[] | Float32Array): AleoEmbeddingChunks;
+    /**
+     * Create chunk with circular offset
+     */
+    private createChunkWithOffset;
+    /**
+     * Validate quantized embedding meets Aleo requirements
+     */
+    validateForAleo(chunks: AleoEmbeddingChunks): void;
+    /**
+     * Calibrate parameters from sample embeddings
+     */
+    calibrateFromSamples(samples: (number[] | Float32Array)[]): {
+        min: number;
+        max: number;
+    };
+}
+/**
+ * Validate facial data quality with detailed scoring
+ */
+declare function validateDataQuality(data: RawFacialData): DataQuality;
+/**
+ * Process facial data for Aleo circuit with complete validation
+ */
+declare function processFacialDataForAleo(face: FaceResult, livenessData: LivenessData, quantizer?: EmbeddingQuantizer): AleoCircuitInputs;
+interface AleoSimHashInputs {
+    simhash_full: string;
+    liveness_combined: string;
+    salt: string;
+}
+interface AleoSimHashInputs {
+    simhash_full: string;
+    liveness_combined: string;
+    salt: string;
+}
+/**
+ * Process facial data using SimHash (Simplified for local testing)
+ */
+declare function generateBiometricSimHash(face: FaceResult, livenessData: LivenessData, averagedEmbedding?: number[]): BiometricSimHashPayload;
+declare function generateRandomSalt(): string;
+declare function createCalibratedQuantizer(samples: (number[] | Float32Array)[]): EmbeddingQuantizer;
+/**
+ * Calculate Hamming Distance between two hex-encoded SimHashes.
+ * Delegates to the canonical byte-level implementation in simHash.ts
+ * to guarantee consistency with the on-chain comparison logic.
+ */
+declare function calculateHammingDistance(hash1: string, hash2: string): number;
+
+/**
+ * Face occlusion checks from a video frame + MediaPipe Face Landmarker points.
+ *
+ * Glasses Detection Overhaul (v2):
+ *  Six independent signals are computed per eye. A bilateral threshold model
+ *  (≥3 signals on both eyes, or ≥4 total + ≥1 bridge signal) fires the
+ *  "glasses detected" flag. An internal per-signal EMA smooths results across
+ *  frames, so a single noisy frame cannot cause a false positive.
+ *
+ * Public API is unchanged — callers of checkFaceOcclusionRaw,
+ * FaceOcclusionTracker, and checkFaceOcclusion need no modifications.
+ */
+interface NormalizedLandmark {
+    x: number;
+    y: number;
+    z?: number;
+}
+interface FaceOcclusionResult {
+    ok: boolean;
+    message?: string;
+}
+interface OcclusionCheckOptions {
+    yawDegrees?: number;
+    duringLivenessFlash?: boolean;
+}
+interface RgbSample {
+    r: number;
+    g: number;
+    b: number;
+    luma: number;
+}
+/**
+ * Stateful glasses detector with per-signal EMA temporal smoothing.
+ * Create one instance and call `update()` on every frame.
+ */
+declare class GlassesDetector {
+    private emaLeft;
+    private emaRight;
+    private emaBridge;
+    private consecutivePositive;
+    private consecutiveNegative;
+    private _detected;
+    reset(): void;
+    get detected(): boolean;
+    /**
+     * Feed a new frame into the detector.
+     * @returns true if glasses are currently detected (after smoothing).
+     */
+    update(skin: RgbSample, ctx: CanvasRenderingContext2D, landmarks: NormalizedLandmark[], imgW: number, imgH: number, options?: OcclusionCheckOptions): boolean;
+}
+/**
+ * Stateful face mask detector with per-signal EMA temporal smoothing.
+ * Create one instance; call update() every frame.
+ */
+declare class MaskDetector {
+    private ema;
+    private consecutivePositive;
+    private consecutiveNegative;
+    private _detected;
+    reset(): void;
+    get detected(): boolean;
+    update(skin: RgbSample, ctx: CanvasRenderingContext2D, landmarks: NormalizedLandmark[], imgW: number, imgH: number): boolean;
+}
+/**
+ * Tracks occlusion across frames with pre-arm debounce and session-violation flag.
+ */
+declare class FaceOcclusionTracker {
+    private armed;
+    private blocked;
+    private obstructionFrames;
+    private clearFrames;
+    private sessionViolation;
+    private lastMessage;
+    private readonly preArmBlockFrames;
+    private readonly violationAfterFrames;
+    private readonly releaseFrames;
+    reset(): void;
+    arm(): void;
+    hasSessionViolation(): boolean;
+    apply(raw: FaceOcclusionResult): FaceOcclusionResult;
+}
+declare function checkFaceOcclusionRaw(landmarks: NormalizedLandmark[], ctx: CanvasRenderingContext2D, width: number, height: number, options?: OcclusionCheckOptions): FaceOcclusionResult;
+/** @deprecated Use tracker + checkFaceOcclusionRaw */
+declare function checkFaceOcclusion(landmarks: NormalizedLandmark[], ctx: CanvasRenderingContext2D, width: number, height: number): FaceOcclusionResult;
+
+/**
+ * Generates deterministic random hyperplanes
+ * These chop the high-dimensional space into 256 regions
+ * @param dimensions Input embedding dimensions
+ * @param count Number of hyperplanes (bits in output hash)
+ */
+declare function generateHyperplanes(dimensions: number, count: number): number[][];
+/**
+ * Computes SimHash for a given embedding
+ * @param embedding The face embedding vector
+ * @param hyperplanes Pre-computed hyperplanes
+ * @returns Hex string representation of the hash
+ */
+declare function computeSimHash(embedding: number[], hyperplanes: number[][]): string;
+/**
+ * Similarity from Hamming distance: 1 - (distance / totalBits).
+ * Same hash => 1, max distance (256) => 0.
+ */
+declare function similarityFromDistance(distance: number, totalBits?: number): number;
+/**
+ * Computes Hamming Distance between two hex strings
+ */
+declare function hammingDistance(hex1: string, hex2: string): number;
+declare function getHyperplanes(dimensions?: number, count?: number): number[][];
+
+type FlashColor = 'red' | 'green' | 'blue' | 'none';
+interface LivenessResult {
+    passed: boolean;
+    score: number;
+    message?: string;
+}
+declare class LivenessEngine {
+    private videoElement;
+    private canvas;
+    private ctx;
+    private flashOverlay;
+    private colorHistory;
+    constructor();
+    setVideoElement(video: HTMLVideoElement): void;
+    setFlashOverlay(overlay: HTMLElement): void;
+    /**
+     * Run the active light reflection sequence
+     * Flashes colors and measures the face bounding box reflection
+     */
+    runLivenessSequence(boundingBox: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }, assertFaceClear?: () => {
+        aligned: boolean;
+        message?: string;
+    }): Promise<LivenessResult>;
+    private flashAndMeasure;
+    private analyzeResults;
+}
+
+/**
+ * Capture quality checks for face verification:
+ * - Lighting (luminance) so we have enough face data
+ * - Face size so the face has enough resolution
+ */
+declare const CAPTURE_QUALITY: {
+    /** Min average luminance in face region (0-255). Below = too dark */
+    readonly LUMINANCE_MIN: 80;
+    /** Max average luminance. Above = overexposed / washed out */
+    readonly LUMINANCE_MAX: 220;
+    /** Min face bounding box width/height in pixels */
+    readonly FACE_MIN_SIZE: 100;
+    /** Ideal min size for best results */
+    readonly FACE_IDEAL_SIZE: 140;
+};
+type FaceBox = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/**
+ * Get face bounding box from Human.js face result (handles multiple formats).
+ */
+declare function getFaceBox(face: {
+    box?: unknown;
+}): FaceBox | null;
+/**
+ * Compute average luminance (0-255) in a region of the canvas.
+ * Uses luminance formula: 0.299*R + 0.587*G + 0.114*B.
+ * Samples every 4th pixel for speed.
+ */
+declare function getRegionLuminance(ctx: CanvasRenderingContext2D, x: number, y: number, width: number, height: number): number;
+/**
+ * Get luminance in the face region. Canvas must already have the current video frame drawn.
+ * Face box can be in pixel or normalized (0-1) coordinates; pass canvas width/height to scale.
+ */
+declare function getFaceLuminance(ctx: CanvasRenderingContext2D, face: {
+    box?: unknown;
+}, canvasWidth: number, canvasHeight: number): number;
+interface CaptureQualityResult {
+    luminance: number;
+    luminanceOk: boolean;
+    faceWidth: number;
+    faceHeight: number;
+    faceSizeOk: boolean;
+    /** True if lighting and face size are both OK */
+    ready: boolean;
+    message: string;
+}
+/**
+ * Evaluate capture quality from luminance and face box size.
+ */
+declare function evaluateCaptureQuality(luminance: number, faceWidth: number, faceHeight: number): CaptureQualityResult;
+
+declare const HUMAN_CONFIG: {
+    modelBasePath: string;
+    backend: "webgpu";
+    async: boolean;
+    cacheSensitivity: number;
+    skipFrame: boolean;
+    warmup: "none";
+    videoOptimized: boolean;
+    deallocate: boolean;
+    face: {
+        enabled: boolean;
+        detector: {
+            enabled: boolean;
+            rotation: boolean;
+            return: boolean;
+            minConfidence: number;
+            maxFaces: number;
+            modelPath: string;
+        };
+        mesh: {
+            enabled: boolean;
+            return: boolean;
+        };
+        landmarks: {
+            enabled: boolean;
+            return: boolean;
+        };
+        emotion: {
+            enabled: boolean;
+            return: boolean;
+            modelPath: string;
+            minConfidence: number;
+        };
+        description: {
+            enabled: boolean;
+            return: boolean;
+            modelPath: string;
+        };
+        iris: {
+            enabled: boolean;
+        };
+        antispoof: {
+            enabled: boolean;
+        };
+        liveness: {
+            enabled: boolean;
+        };
+    };
+    filter: {
+        enabled: boolean;
+    };
+    body: {
+        enabled: boolean;
+    };
+    hand: {
+        enabled: boolean;
+    };
+    object: {
+        enabled: boolean;
+    };
+    gesture: {
+        enabled: boolean;
+        return: boolean;
+        minConfidence: number;
+    };
+    debug: boolean;
+    profile: boolean;
+};
+declare const VERIFICATION_CONSTANTS: {
+    HAPPY_SUSTAIN_DURATION: number;
+    BLINK_REQUIRED_COUNT: number;
+    BLINK_COOLDOWN: number;
+    PROCESS_INTERVAL: number;
+    FPS_UPDATE_INTERVAL: number;
+    DEBUG_LOG_INTERVAL: number;
+    PROCESS_WIDTH: number;
+    PROCESS_HEIGHT: number;
+    SKIP_FRAMES: number;
+};
+declare const BACKEND_PRIORITY: readonly ["webgpu", "webgl", "wasm"];
+
+type ChainType = 'solana' | 'evm';
+interface VerificationPayload {
+    simhashFull: string;
+    livenessCombined: number;
+    walletAddress: string;
+    chain: ChainType;
+}
+interface RelayerConfig {
+    baseUrl: string;
+    network?: 'mainnet' | 'testnet';
+    /**
+     * The application ID assigned to your project.
+     * Required for production usage to bypass origin restrictions.
+     */
+    appId?: string;
+}
+interface RelayerResponse {
+    success: boolean;
+    txHash?: string;
+    data?: any;
+}
+declare class VerifiedRelayerClient {
+    private baseUrl;
+    private network;
+    private appId?;
+    constructor(config: RelayerConfig);
+    /**
+     * Submits the face verification payload to the backend relayer.
+     * The backend handles gas abstraction and execution for both EVM and Solana users.
+     */
+    submitVerification(payload: VerificationPayload): Promise<RelayerResponse>;
+}
+
+interface VisionModels {
+    faceLandmarker: FaceLandmarker | null;
+    human: Human | null;
+    isInitialized: boolean;
+    error: string | null;
+}
+declare const useVisionModels: () => VisionModels;
+
+declare function useCameraStream(isReady: boolean): {
+    stream: MediaStream | null;
+    error: string | null;
+    startCamera: () => Promise<void>;
+};
+
+interface FaceZKProps {
+    onBiometricData?: (payload: {
+        simhash_full: string;
+    }) => void;
+    onVerificationComplete?: (result: any) => void;
+    onContinue?: () => void;
+    className?: string;
+}
+
+declare const FaceZKInner: React.FC<FaceZKProps>;
+
+interface ProofOfHumanityProps {
+    onNextStep: () => void;
+    onBiometricData?: (data: {
+        simhash_full: string;
+    }) => void;
+    onVerificationComplete?: (result: VerificationResult) => void;
+    className?: string;
+    containerClassName?: string;
+    buttonClassName?: string;
+}
+declare const ProofOfHumanity: React.FC<ProofOfHumanityProps>;
+
+interface VerifiedOnchainFlowProps {
+    relayerUrl?: string;
+    requiredSocials?: Array<'farcaster' | 'lens' | 'x' | 'tiktok' | 'instagram' | 'youtube' | string>;
+    requiredWallets?: Array<'phantom' | 'backpack' | 'metamask' | 'rainbow' | string>;
+    requireBiometrics?: boolean;
+    onIdentityVerified: (data: VerifiedIdentityData) => void;
+    className?: string;
+    environment?: 'mainnet' | 'testnet';
+    appId?: string;
+}
+interface VerifiedIdentityData {
+    walletAddress: string;
+    chain: 'evm' | 'solana';
+    socialProfile?: any;
+    socialPlatform?: string;
+    humanityCode?: string;
+    simHash?: string;
+}
+declare const VerifiedOnchainFlow: React.FC<VerifiedOnchainFlowProps>;
+
+interface WalletSelectionProps {
+    onWalletConnect: (walletSlug: string) => void;
+    className?: string;
+    requiredWallets?: Array<'phantom' | 'backpack' | 'metamask' | 'rainbow' | string>;
+}
+declare const WalletSelection: React.FC<WalletSelectionProps>;
+
+interface SocialConnectionProps {
+    onSocialConnect: (platform: string, profileData?: any) => void;
+    onNextStep: () => void;
+    userAddress?: string;
+    availableSocials: string[];
+    className?: string;
+    backendUrl?: string;
+    environment?: 'mainnet' | 'testnet';
+}
+declare const SocialConnection: React.FC<SocialConnectionProps>;
+
+export { type AleoCircuitInputs, type AleoCircuitInputsComplete, type AleoEmbeddingChunks, type AleoSimHashInputs, BACKEND_PRIORITY, type BiometricSimHashPayload, CAPTURE_QUALITY, type CaptureQualityResult, type ChainType, type DataQuality, EmbeddingQuantizer, type FaceBox, type FaceOcclusionResult, FaceOcclusionTracker, FaceZKInner as FaceZK, type FlashColor, GlassesDetector, HUMAN_CONFIG, type LivenessData, LivenessEngine, type LivenessResult, MaskDetector, type NormalizedLandmark, type OcclusionCheckOptions, ProofOfHumanity, type RawFacialData, type RelayerConfig, type RelayerResponse, SocialConnection, VERIFICATION_CONSTANTS, type VerificationPayload, type VerificationResult, type VerifiedIdentityData, VerifiedOnchainFlow, type VerifiedOnchainFlowProps, VerifiedRelayerClient, type VisionModels, WalletSelection, averageEmbeddings, calculateHammingDistance, checkFaceOcclusion, checkFaceOcclusionRaw, computeSimHash, createCalibratedQuantizer, createLivenessData, evaluateCaptureQuality, extractRawFacialData, generateBiometricSimHash, generateHyperplanes, generateRandomSalt, getFaceBox, getFaceLuminance, getHyperplanes, getRegionLuminance, hammingDistance, normalizeEmbedding, processFacialDataForAleo, similarityFromDistance, useCameraStream, useVisionModels, validateDataQuality };