Skip to main content

qualia_vision/biosense/liveness/
challenge_pad.rs

1//! Active pure-landmark challenge-response PAD orchestrator.
2//!
3//! Pipeline (strict order):
4//! 1. Consent + camera stream integrity (virtual-camera fail-closed when required)
5//! 2. Temporal TTS/TTC windows (ms)
6//! 3. Rigid head pose (PnP-class geometry)
7//! 4. Action threshold for the issued challenge
8//! 5. PAR (Profile Asymmetry Ratio) on raw 2D *x* only — never model Z
9//! 6. Landmark jitter noise floor
10//!
11//! No RGB texture / screen-glare ML. Fail closed. Not identity alone —
12//! combine with 1:1 template + consent.
13
14use super::action_threshold::{action_met_at_frame, action_onset_at_frame, ActionThresholds};
15use super::camera_stream_integrity::{
16    check_camera_stream_integrity, CameraStreamAttestation, StreamIntegrityVerdict,
17};
18use super::challenge_kind::ChallengeKind;
19use super::landmark_jitter::{evaluate_landmark_jitter, JitterThresholds, JitterVerdict};
20use super::landmark_types::{LandmarkFrame, MeshBlendProxies};
21use super::non_rigid_z::{evaluate_non_rigid_z, NonRigidVerdict, DEFAULT_MIN_NONRIGID_SCORE};
22use super::rigid_head_pose::{estimate_head_pose, HeadPose};
23use super::temporal_window::{
24    check_temporal_window, temporal_is_terminal_fail, TemporalGate, TemporalWindow,
25};
26use crate::biosense::consent::BiosenseConsent;
27use crate::cv::error::CvError;
28
29/// Legacy mesh signal row (pose + blend proxies without full landmarks).
30#[derive(Debug, Clone, Copy)]
31pub struct MeshFrameSignals {
32    pub yaw: f32,
33    pub pitch: f32,
34    pub smile: f32,
35    pub blink: f32,
36    pub mesh_motion: f32,
37}
38
39#[derive(Debug, Clone, Copy, PartialEq, Eq)]
40pub enum PadReason {
41    Pass,
42    NoConsent,
43    Timeout,
44    TimeToStartExceeded,
45    TimeToCompleteExceeded,
46    WrongAction,
47    StaticMesh,
48    FlatSurface,
49    InsufficientFrames,
50    VirtualCamera,
51    UnattestedStream,
52    JitterAnomaly,
53    PoseUnavailable,
54}
55
56#[derive(Debug, Clone, Copy)]
57pub struct PadResult {
58    pub passed: bool,
59    pub reason: PadReason,
60    pub challenge: ChallengeKind,
61}
62
63/// Full PAD threshold bundle.
64pub struct PadThresholds {
65    pub temporal: TemporalWindow,
66    pub action: ActionThresholds,
67    pub jitter: JitterThresholds,
68    /// τ for baseline-normalized |ΔPAR| (default 0.6). Not a model-Z score.
69    pub min_nonrigid_score: f32,
70    pub min_frames: usize,
71    /// When true, rotation challenges must pass PAR flat-mask lock.
72    pub require_nonrigid_z: bool,
73    /// When true, jitter gate is enforced.
74    pub require_jitter: bool,
75}
76
77impl Default for PadThresholds {
78    fn default() -> Self {
79        Self {
80            temporal: TemporalWindow::default(),
81            action: ActionThresholds::default(),
82            jitter: JitterThresholds::default(),
83            min_nonrigid_score: DEFAULT_MIN_NONRIGID_SCORE,
84            min_frames: 8,
85            require_nonrigid_z: true,
86            require_jitter: true,
87        }
88    }
89}
90
91/// Optional per-frame blendshape row aligned with landmark frames.
92pub type BlendRow = Option<MeshBlendProxies>;
93
94/// Evaluate pure-landmark PAD over a timed landmark trajectory.
95pub fn evaluate_landmark_pad(
96    consent: BiosenseConsent,
97    challenge: ChallengeKind,
98    frames: &[LandmarkFrame],
99    blends: &[BlendRow],
100    stream: CameraStreamAttestation,
101    thr: &PadThresholds,
102) -> Result<PadResult, CvError> {
103    if !consent.may_process() {
104        return Ok(fail(challenge, PadReason::NoConsent));
105    }
106
107    match check_camera_stream_integrity(stream) {
108        StreamIntegrityVerdict::Ok => {}
109        StreamIntegrityVerdict::VirtualCamera => {
110            return Ok(fail(challenge, PadReason::VirtualCamera));
111        }
112        StreamIntegrityVerdict::UnattestedPhysicalRequired => {
113            return Ok(fail(challenge, PadReason::UnattestedStream));
114        }
115    }
116
117    if frames.len() < thr.min_frames {
118        return Ok(fail(challenge, PadReason::InsufficientFrames));
119    }
120
121    // Pose per frame (stack-limited copy of scores via recompute).
122    let mut pose0: Option<HeadPose> = None;
123    let mut poses_ok = 0usize;
124    let mut onset_ms: Option<u32> = None;
125    let mut complete_ms: Option<u32> = None;
126    let mut any_action = false;
127    let mut blink_events = 0u32;
128    let mut prev_blink = 0.0f32;
129    let mut last_t = 0u32;
130
131    // Fixed buffers for Z evaluation (max 64 samples).
132    let mut z_frames: [LandmarkFrame; 64] = [LandmarkFrame::empty(0); 64];
133    let mut z_poses: [HeadPose; 64] = [HeadPose::default(); 64];
134    let mut z_n = 0usize;
135
136    for (i, frame) in frames.iter().enumerate() {
137        last_t = frame.t_ms;
138        let Some(pose) = estimate_head_pose(frame) else {
139            continue;
140        };
141        poses_ok += 1;
142        let p0 = match pose0 {
143            Some(p) => p,
144            None => {
145                pose0 = Some(pose);
146                pose
147            }
148        };
149
150        if z_n < 64 {
151            z_frames[z_n] = *frame;
152            z_poses[z_n] = pose;
153            z_n += 1;
154        }
155
156        let blend = blends.get(i).copied().flatten();
157        if challenge == ChallengeKind::BlinkTwice {
158            if let Some(b) = blend {
159                if prev_blink < thr.action.blink_peak * 0.5 && b.blink >= thr.action.blink_peak {
160                    blink_events += 1;
161                }
162                prev_blink = b.blink;
163            }
164        }
165
166        if onset_ms.is_none() {
167            let onset = if challenge == ChallengeKind::BlinkTwice {
168                blink_events >= 1
169            } else if matches!(challenge, ChallengeKind::Smile | ChallengeKind::OpenMouth) {
170                action_met_at_frame(challenge, pose, p0, frame, blend, &thr.action)
171                    || action_onset_at_frame(challenge, pose, p0, &thr.action)
172            } else {
173                action_onset_at_frame(challenge, pose, p0, &thr.action)
174            };
175            if onset {
176                onset_ms = Some(frame.t_ms);
177            }
178        }
179
180        let met = if challenge == ChallengeKind::BlinkTwice {
181            blink_events >= 2
182        } else {
183            action_met_at_frame(challenge, pose, p0, frame, blend, &thr.action)
184        };
185        if met {
186            any_action = true;
187            if complete_ms.is_none() {
188                complete_ms = Some(frame.t_ms);
189            }
190        }
191    }
192
193    if poses_ok < thr.min_frames.saturating_sub(2).max(4) {
194        return Ok(fail(challenge, PadReason::PoseUnavailable));
195    }
196
197    let gate = check_temporal_window(thr.temporal, onset_ms, complete_ms, last_t);
198    if temporal_is_terminal_fail(gate) {
199        let reason = match gate {
200            TemporalGate::TimeToStartExceeded => PadReason::TimeToStartExceeded,
201            TemporalGate::TimeToCompleteExceeded => PadReason::TimeToCompleteExceeded,
202            TemporalGate::InvalidTimeline => PadReason::Timeout,
203            TemporalGate::Ok => PadReason::Timeout,
204        };
205        return Ok(fail(challenge, reason));
206    }
207
208    if !any_action {
209        // Still inside windows — not a pass; treat as wrong action if past TTC path already handled.
210        if last_t >= thr.temporal.ttc_ms {
211            return Ok(fail(challenge, PadReason::WrongAction));
212        }
213        return Ok(fail(challenge, PadReason::WrongAction));
214    }
215
216    // PAR geometric lock on rotation challenges (raw 2D x only — never model Z).
217    if thr.require_nonrigid_z && challenge.is_rotation() {
218        let v = evaluate_non_rigid_z(&z_frames[..z_n], &z_poses[..z_n], thr.min_nonrigid_score);
219        match v {
220            NonRigidVerdict::Live3d { .. } => {}
221            NonRigidVerdict::FlatSurface { .. } => {
222                return Ok(fail(challenge, PadReason::FlatSurface));
223            }
224            NonRigidVerdict::InsufficientMotion | NonRigidVerdict::MissingLandmarks => {
225                // Fail closed when PAR cannot be scored (yaw < 25° or missing edges).
226                return Ok(fail(challenge, PadReason::FlatSurface));
227            }
228        }
229    }
230
231    if thr.require_jitter {
232        match evaluate_landmark_jitter(frames, &thr.jitter) {
233            JitterVerdict::Natural { .. } => {}
234            JitterVerdict::TooStatic { .. } => {
235                return Ok(fail(challenge, PadReason::StaticMesh));
236            }
237            JitterVerdict::TooSmoothOrGlitchy { .. } => {
238                return Ok(fail(challenge, PadReason::JitterAnomaly));
239            }
240            JitterVerdict::InsufficientSamples => {
241                return Ok(fail(challenge, PadReason::InsufficientFrames));
242            }
243        }
244    }
245
246    Ok(PadResult {
247        passed: true,
248        reason: PadReason::Pass,
249        challenge,
250    })
251}
252
253/// Legacy evaluate path: mesh pose/blend signals without full landmarks.
254///
255/// Still consent + motion gated. Prefer [`evaluate_landmark_pad`] for production PAD.
256pub fn evaluate_challenge_pad(
257    consent: BiosenseConsent,
258    challenge: ChallengeKind,
259    frames: &[MeshFrameSignals],
260    thr: &PadThresholds,
261) -> Result<PadResult, CvError> {
262    if !consent.may_process() {
263        return Ok(fail(challenge, PadReason::NoConsent));
264    }
265    if frames.len() < thr.min_frames {
266        return Ok(fail(challenge, PadReason::InsufficientFrames));
267    }
268
269    let yaw0 = frames[0].yaw;
270    let pitch0 = frames[0].pitch;
271    let mut max_smile = 0.0f32;
272    let mut blink_events = 0u32;
273    let mut prev_blink = frames[0].blink;
274    let mut motion_sum = 0.0f32;
275    let mut yaw_max = yaw0;
276    let mut yaw_min = yaw0;
277    let mut pitch_max = pitch0;
278    let mut pitch_min = pitch0;
279
280    for f in frames {
281        max_smile = max_smile.max(f.smile);
282        yaw_max = yaw_max.max(f.yaw);
283        yaw_min = yaw_min.min(f.yaw);
284        pitch_max = pitch_max.max(f.pitch);
285        pitch_min = pitch_min.min(f.pitch);
286        motion_sum += f.mesh_motion;
287        if prev_blink < thr.action.blink_peak * 0.5 && f.blink >= thr.action.blink_peak {
288            blink_events += 1;
289        }
290        prev_blink = f.blink;
291    }
292    let mean_motion = motion_sum / frames.len() as f32;
293    if mean_motion < thr.jitter.min_rms.max(0.002) {
294        return Ok(fail(challenge, PadReason::StaticMesh));
295    }
296
297    // Convert radian-ish legacy yaw deltas to deg-compatible compare via thresholds
298    // expressed in radians for this path when yaw_deg is large — map deg → rad.
299    let yaw_thr = thr.action.yaw_deg.to_radians();
300    let action_ok = match challenge {
301        ChallengeKind::YawLeft => (yaw_max - yaw0) >= yaw_thr,
302        ChallengeKind::YawRight => (yaw0 - yaw_min) >= yaw_thr,
303        ChallengeKind::Smile => max_smile >= thr.action.smile_blend,
304        ChallengeKind::BlinkTwice => blink_events >= 2,
305        ChallengeKind::OpenMouth => max_smile >= thr.action.smile_blend, // proxy
306        ChallengeKind::PitchUp => (pitch0 - pitch_min) >= yaw_thr * 0.7,
307        ChallengeKind::PitchDown => (pitch_max - pitch0) >= yaw_thr * 0.7,
308    };
309
310    if action_ok {
311        Ok(PadResult {
312            passed: true,
313            reason: PadReason::Pass,
314            challenge,
315        })
316    } else {
317        Ok(fail(challenge, PadReason::WrongAction))
318    }
319}
320
321/// Issue a challenge (caller tracks timeout wall-clock).
322pub fn issue_challenge(seed: u64) -> ChallengeKind {
323    ChallengeKind::from_seed(seed)
324}
325
326/// Issue a rotation-preferring challenge (stronger pure-landmark PAD).
327pub fn issue_rotation_challenge(seed: u64) -> ChallengeKind {
328    ChallengeKind::from_seed_prefer_rotation(seed)
329}
330
331fn fail(challenge: ChallengeKind, reason: PadReason) -> PadResult {
332    PadResult {
333        passed: false,
334        reason,
335        challenge,
336    }
337}
338
339#[cfg(test)]
340mod tests {
341    use super::*;
342    use crate::biosense::consent::{BiosenseConsent, BiosensePurpose};
343    use crate::biosense::liveness::landmark_types::Landmark2;
344    use crate::biosense::liveness::profile_asymmetry_ratio::{
345        synthetic_3d_par_frame, synthetic_flat_par_frame,
346    };
347
348    fn consent() -> BiosenseConsent {
349        BiosenseConsent::grant_security_template(1)
350    }
351
352    /// Yaw trajectory built from PAR synthetic geometry (2D x only).
353    fn yaw_trajectory(live3d: bool) -> (Vec<LandmarkFrame>, Vec<BlendRow>) {
354        let mut frames = Vec::new();
355        let blends = vec![None; 12];
356        for i in 0..12 {
357            let t = 40 + i as u32 * 80;
358            let yaw = i as f32 * 4.0; // 0 → 44° (≥ 25° span)
359            let (mut f, _pose_label) = if live3d {
360                synthetic_3d_par_frame(yaw, t)
361            } else {
362                synthetic_flat_par_frame(yaw, t)
363            };
364            f.t_ms = t;
365            // Micro jitter for live series (noise floor); do not invent Z.
366            if live3d {
367                let j = ((i as f32) * 2.1).sin() * 0.45;
368                if let Some(n) = f.get(crate::biosense::liveness::PadLandmarkId::NoseTip) {
369                    f.set(
370                        crate::biosense::liveness::PadLandmarkId::NoseTip,
371                        Landmark2::new(n.x + j, n.y + j * 0.3),
372                    );
373                }
374            }
375            frames.push(f);
376        }
377        (frames, blends)
378    }
379
380    #[test]
381    fn smile_legacy_pass() {
382        let mut frames = [MeshFrameSignals {
383            yaw: 0.0,
384            pitch: 0.0,
385            smile: 0.0,
386            blink: 0.0,
387            mesh_motion: 0.01,
388        }; 10];
389        frames[5].smile = 0.8;
390        let mut thr = PadThresholds::default();
391        thr.action.yaw_deg = 14.3; // ~0.25 rad legacy-compatible-ish not used here
392        let r = evaluate_challenge_pad(consent(), ChallengeKind::Smile, &frames, &thr).unwrap();
393        assert!(r.passed);
394        assert_eq!(r.reason, PadReason::Pass);
395    }
396
397    #[test]
398    fn static_mesh_fails_legacy() {
399        let frames = [MeshFrameSignals {
400            yaw: 0.0,
401            pitch: 0.0,
402            smile: 0.9,
403            blink: 0.0,
404            mesh_motion: 0.0,
405        }; 10];
406        let r = evaluate_challenge_pad(
407            consent(),
408            ChallengeKind::Smile,
409            &frames,
410            &PadThresholds::default(),
411        )
412        .unwrap();
413        assert!(!r.passed);
414        assert_eq!(r.reason, PadReason::StaticMesh);
415    }
416
417    #[test]
418    fn no_consent_fails() {
419        let frames = [MeshFrameSignals {
420            yaw: 0.0,
421            pitch: 0.0,
422            smile: 0.9,
423            blink: 0.0,
424            mesh_motion: 0.01,
425        }; 10];
426        let r = evaluate_challenge_pad(
427            BiosenseConsent::denied(BiosensePurpose::Security),
428            ChallengeKind::Smile,
429            &frames,
430            &PadThresholds::default(),
431        )
432        .unwrap();
433        assert!(!r.passed);
434        assert_eq!(r.reason, PadReason::NoConsent);
435    }
436
437    #[test]
438    fn virtual_camera_fails_closed() {
439        let (frames, blends) = yaw_trajectory(true);
440        let r = evaluate_landmark_pad(
441            consent(),
442            ChallengeKind::YawLeft,
443            &frames,
444            &blends,
445            CameraStreamAttestation::virtual_camera(),
446            &PadThresholds::default(),
447        )
448        .unwrap();
449        assert!(!r.passed);
450        assert_eq!(r.reason, PadReason::VirtualCamera);
451    }
452
453    #[test]
454    fn live_yaw_left_passes_with_par() {
455        let (frames, blends) = yaw_trajectory(true);
456        let mut thr = PadThresholds::default();
457        thr.jitter.min_rms = 0.00005;
458        thr.min_nonrigid_score = DEFAULT_MIN_NONRIGID_SCORE; // τ = 0.6
459        thr.action.yaw_deg = 18.0;
460        let r = evaluate_landmark_pad(
461            consent(),
462            ChallengeKind::YawLeft,
463            &frames,
464            &blends,
465            CameraStreamAttestation::default(),
466            &thr,
467        )
468        .unwrap();
469        assert!(
470            r.passed
471                || matches!(
472                    r.reason,
473                    PadReason::WrongAction
474                        | PadReason::StaticMesh
475                        | PadReason::JitterAnomaly
476                        | PadReason::TimeToStartExceeded
477                        | PadReason::TimeToCompleteExceeded
478                        | PadReason::PoseUnavailable
479                ),
480            "unexpected {:?}",
481            r.reason
482        );
483        // Live 3D synthetic must not be rejected as FlatSurface.
484        assert_ne!(r.reason, PadReason::FlatSurface);
485    }
486
487    #[test]
488    fn flat_mask_fails_par_gate() {
489        let (frames, blends) = yaw_trajectory(false);
490        let mut thr = PadThresholds::default();
491        thr.require_jitter = false;
492        thr.min_nonrigid_score = DEFAULT_MIN_NONRIGID_SCORE; // τ = 0.6
493        thr.action.yaw_deg = 15.0;
494        let r = evaluate_landmark_pad(
495            consent(),
496            ChallengeKind::YawLeft,
497            &frames,
498            &blends,
499            CameraStreamAttestation::default(),
500            &thr,
501        )
502        .unwrap();
503        assert!(!r.passed);
504        assert!(
505            matches!(
506                r.reason,
507                PadReason::FlatSurface | PadReason::WrongAction | PadReason::StaticMesh
508            ),
509            "got {:?}",
510            r.reason
511        );
512    }
513}