Liveness and anti-spoof
The current SDK ships passive anti-spoof only. A Silent-Face-Anti-Spoofing ONNX model runs in a worker on the captured frame and produces a real-confidence score. Below antispoofThreshold (default 0.7), the session retries up to maxAntispoofRetries (default 3) times, then throws a QualityError with code ANTISPOOF_FAILED.
What it catches
- Printed photographs held in front of the camera.
- Many screen replays from low-quality displays.
- Off-angle or poorly lit spoofs.
What it does not catch
- High-quality video replays on a colour-accurate display.
- 3D-printed or silicone masks.
- Faces composited via a virtual camera driver.
Treat anti-spoof as one layer of defence, not a guarantee. Pair it with workflow controls (in-person enrollment, supervised capture) when the threat model demands it.
Active challenges
Active challenge types (BLINK, SMILE, TURN_LEFT, TURN_RIGHT) are declared in the type system but not yet implemented. Passing a non-empty activeChallenges array throws CaptureError with code NOT_IMPLEMENTED_V0. Track the changelog for activation.
False-reject behaviour
The model errs on the side of false-reject when:
- The face is in extreme backlight or shadow.
- The face is more than ~45° off-axis.
- A printed photo is held very close to the camera (paradoxically — the high-frequency texture of paper at close range looks unnatural to the model).
In these cases the user sees retry prompts. Improve the lighting or framing and the capture succeeds.