face-verification-iyx

Browser-based face liveness verification SDK — challenge-based liveness, identity check (catches mid-session face swaps), and built-in collection of device, network, geolocation and risk metadata with a signed payload.

Install

npm install face-verification-iyx

Use

<script type="module">
  import LivenessSDK from "face-verification-iyx";

  const sdk = new LivenessSDK({
    apiUrl: "https://your-backend.example/verify",
    challengeCount: 3,
    verifyingFor: "Rathish Kumar",
    enableIPCollection: true,
    enableGeolocation: true,
    enableDeviceFingerprint: true,
    onSuccess: (r) => console.log("verified", r),
    onError:   (e) => console.error("failed", e),
  });

  await sdk.start();
</script>

The SDK renders its own UI (circular camera, pulsing ring, live hints), runs three random liveness challenges (blink, head-left, head-right) plus a final straight-on hold, captures an image and a 3-second video, collects metadata, signs the payload, and POSTs it to apiUrl.

Config

interface LivenessConfig {
  apiUrl?: string;
  method?: "POST" | "PUT";
  headers?: Record<string, string>;
  body?: Record<string, any>;
  imageFieldName?: string;       // enables multipart/form-data
  videoFieldName?: string;       // enables multipart/form-data
  challengeCount?: number;       // 1-3
  ipResolverUrl?: string;        // tried first; falls back to public providers
  enableGeolocation?: boolean;
  enableIPCollection?: boolean;
  enableDeviceFingerprint?: boolean;
  verifyingFor?: string;         // shown in UI, included in payload
  identityCheck?: boolean;       // continuous same-person check (default true)
  onSuccess?: (r) => void;
  onError?:   (e) => void;
  onProgress?: (p) => void;
  onChallengeStart?: (c) => void;
  onChallengeComplete?: (c, passed) => void;
}

Payload your backend receives

{
  "session_id": "...",
  "sdk_version": "2.0.0",
  "verifying_for": "Rathish Kumar",
  "face_image": "data:image/jpeg;base64,...",
  "liveness_video": "data:video/webm;base64,...",
  "location":      { "latitude": 0, "longitude": 0, "accuracy": 0, "timestamp": "ISO" },
  "network":       { "ip_address": "", "ip_version": "IPv4", "user_agent": "", "timezone": "", "language": "" },
  "device":        { "fingerprint": "sha256", "platform": "", "screen_resolution": "1920x1080@24", "hardware_concurrency": 8 },
  "risk_analysis": { "vpn_detected": false, "proxy_detected": false, "mock_location_suspected": false, "risk_score": 0 },
  "timestamp": "ISO",
  "nonce": "32-byte hex",
  "integrity_hash": "sha256(canonicalJSON(payload_minus_hash) + nonce)"
}

Optional fields are omitted (not sent as null) when their enable* flag is false.

Security

• 32-byte crypto-random nonce per session.
• SHA-256 integrity hash over canonical (sorted-keys) JSON. Backend re-hashes to detect tampering.
• Continuous face identity check via landmark geometry — flags mid-session person swaps.
• HTTPS required in production (geolocation + MediaPipe ESM).

Browser support

Modern evergreen browsers (Chrome 90+, Edge 90+, Firefox 88+, Safari 15+). Requires: camera permission, MediaRecorder, crypto.subtle, RTCPeerConnection (optional, for WebRTC leak check).

License

MIT