facezkp/dist/types/index.ts

Face analysis library with liveness detection, biometric template extraction, and fuzzy hashing for privacy-preserving identity verification.

/**
 * FaceZK Library Types
 * ZK-AI Proof of Humanity: Live Selfie Check
 */

import type { Tensor, Tensor4D } from '@tensorflow/tfjs-core';

/** Supported input types for face analysis */
export type Input =
  | HTMLImageElement
  | HTMLVideoElement
  | HTMLCanvasElement
  | ImageData
  | ImageBitmap
  | Tensor
  | Tensor4D;

/** Backend options for TensorFlow.js */
export type Backend = 'webgl' | 'wasm' | 'cpu';

/** Liveness detection challenges */
export type LivenessChallenge = 'blink' | 'head-turn' | 'smile' | 'mouth-open';

/** Biometric template structure */
export interface BiometricTemplate {
  /** Unique identifier for the template */
  id: string;
  /** Face descriptor vector (normalized) */
  descriptor: number[];
  /** Face mesh keypoints (468 points) */
  mesh: number[][];
  /** Face bounding box */
  box: [number, number, number, number];
  /** Confidence score */
  confidence: number;
  /** Timestamp of creation */
  timestamp: number;
}

/** Liveness detection result */
export interface LivenessResult {
  /** Overall liveness score (0-1) */
  score: number;
  /** Is the person alive */
  isAlive: boolean;
  /** Detected challenges */
  challenges: {
    [key in LivenessChallenge]: {
      detected: boolean;
      confidence: number;
    };
  };
  /** Anti-spoofing score */
  antiSpoofScore: number;
  /** Timestamp */
  timestamp: number;
}

/** Humanity verification result */
export interface HumanityResult {
  /** Biometric template */
  template: BiometricTemplate;
  /** Liveness detection result */
  liveness: LivenessResult;
  /** Non-reversible ID (Sₐ) */
  biometricId: string;
  /** Humanity Code (Hₐ) */
  humanityCode: string;
  /** Verification passed */
  verified: boolean;
  /** Error message if verification failed */
  error?: string;
}

/** Configuration for FaceZK library */
export interface FaceZKConfig {
  /** TensorFlow.js backend */
  backend: Backend;
  /** Debug mode */
  debug: boolean;
  /** Model base path */
  modelBasePath: string;
  /** System salt for humanity code generation */
  systemSalt: string;
  /** Minimum confidence for face detection */
  minConfidence: number;
  /** Minimum liveness score */
  minLivenessScore: number;
  /** Liveness challenges to perform */
  challenges: LivenessChallenge[];
  /** Face detection settings */
  face: {
    /** Enable face detection */
    enabled: boolean;
    /** Maximum number of faces to detect */
    maxFaces: number;
    /** Minimum face size in pixels */
    minSize: number;
    /** Face rotation correction */
    rotation: boolean;
  };
  /** Liveness detection settings */
  liveness: {
    /** Enable liveness detection */
    enabled: boolean;
    /** Number of frames to analyze */
    frameCount: number;
    /** Timeout for challenge completion */
    timeout: number;
  };
  /** Biometric settings */
  biometric: {
    /** Enable biometric template extraction */
    enabled: boolean;
    /** Descriptor vector size */
    descriptorSize: number;
    /** Normalization method */
    normalization: 'l2' | 'minmax';
  };
}

/** Liveness detection state */
export interface LivenessState {
  /** Collected frame analyses */
  frames: any[];
  /** Current challenge being performed */
  currentChallenge?: LivenessChallenge;
  /** Challenge start time */
  challengeStartTime: number;
  /** Challenge completion status */
  challenges: {
    [key in LivenessChallenge]: {
      completed: boolean;
      confidence: number;
      frames: number;
    };
  };
}

/** Session state for live verification */
export interface VerificationSession {
  /** Session ID */
  id: string;
  /** Current state */
  state: 'initializing' | 'detecting' | 'challenging' | 'verifying' | 'completed' | 'failed';
  /** Current challenge */
  currentChallenge?: LivenessChallenge;
  /** Collected frames */
  frames: Tensor4D[];
  /** Progress (0-1) */
  progress: number;
  /** Start time */
  startTime: number;
  /** Liveness detection state */
  livenessState?: LivenessState;
  /** Result */
  result?: HumanityResult;
}

/** Event types for verification session */
export type VerificationEvent =
  | 'session-start'
  | 'face-detected'
  | 'challenge-start'
  | 'challenge-complete'
  | 'verification-complete'
  | 'verification-failed'
  | 'error';

/** Event listener callback */
export type VerificationEventListener = (event: VerificationEvent, data?: any) => void;

/** Empty result template */
export const emptyHumanityResult = (): HumanityResult => ({
  template: {
    id: '',
    descriptor: [],
    mesh: [],
    box: [0, 0, 0, 0],
    confidence: 0,
    timestamp: 0,
  },
  liveness: {
    score: 0,
    isAlive: false,
    challenges: {
      blink: { detected: false, confidence: 0 },
      'head-turn': { detected: false, confidence: 0 },
      smile: { detected: false, confidence: 0 },
      'mouth-open': { detected: false, confidence: 0 },
    },
    antiSpoofScore: 0,
    timestamp: 0,
  },
  biometricId: '',
  humanityCode: '',
  verified: false,
});