Skip to main content

qualia_vision/biosense/liveness/
temporal_window.rs

1//! Strict millisecond challenge windows (TTS / TTC).
2//!
3//! Prevents deepfake/replay brute-forcing by requiring the geometric action
4//! to *start* and *complete* inside fixed local-clock bounds.
5
6/// Default time-to-start: subject must begin geometric motion within this many ms.
7pub const DEFAULT_TTS_MS: u32 = 800;
8/// Default time-to-complete: action must cross threshold by this many ms.
9pub const DEFAULT_TTC_MS: u32 = 2000;
10
11#[derive(Debug, Clone, Copy, PartialEq, Eq)]
12pub enum TemporalGate {
13    /// Within both TTS and TTC windows for the observed events.
14    Ok,
15    /// No motion / action onset observed by TTS.
16    TimeToStartExceeded,
17    /// Action did not reach threshold by TTC.
18    TimeToCompleteExceeded,
19    /// Sample times empty or ill-ordered.
20    InvalidTimeline,
21}
22
23#[derive(Debug, Clone, Copy)]
24pub struct TemporalWindow {
25    pub tts_ms: u32,
26    pub ttc_ms: u32,
27}
28
29impl Default for TemporalWindow {
30    fn default() -> Self {
31        Self {
32            tts_ms: DEFAULT_TTS_MS,
33            ttc_ms: DEFAULT_TTC_MS,
34        }
35    }
36}
37
38/// Evaluate TTS/TTC against observed onset and completion times (ms since issue).
39///
40/// * `onset_ms` — first frame where action trajectory is detectably underway
41///   (e.g. |Δyaw| > 0.15 × threshold). `None` if never started.
42/// * `complete_ms` — first frame where full action threshold is met. `None` if never.
43/// * `last_sample_ms` — last landmark sample time (for incomplete timelines).
44pub fn check_temporal_window(
45    window: TemporalWindow,
46    onset_ms: Option<u32>,
47    complete_ms: Option<u32>,
48    last_sample_ms: u32,
49) -> TemporalGate {
50    if window.tts_ms == 0 || window.ttc_ms == 0 || window.tts_ms > window.ttc_ms {
51        return TemporalGate::InvalidTimeline;
52    }
53
54    match onset_ms {
55        None => {
56            if last_sample_ms >= window.tts_ms {
57                TemporalGate::TimeToStartExceeded
58            } else {
59                // Still inside TTS — caller should keep sampling, not fail yet.
60                TemporalGate::Ok
61            }
62        }
63        Some(onset) if onset > window.tts_ms => TemporalGate::TimeToStartExceeded,
64        Some(_) => match complete_ms {
65            Some(done) if done <= window.ttc_ms => TemporalGate::Ok,
66            Some(_) => TemporalGate::TimeToCompleteExceeded,
67            None if last_sample_ms >= window.ttc_ms => TemporalGate::TimeToCompleteExceeded,
68            None => TemporalGate::Ok, // still inside TTC
69        },
70    }
71}
72
73/// Whether the session must hard-fail now (vs keep collecting frames).
74pub fn temporal_is_terminal_fail(gate: TemporalGate) -> bool {
75    matches!(
76        gate,
77        TemporalGate::TimeToStartExceeded
78            | TemporalGate::TimeToCompleteExceeded
79            | TemporalGate::InvalidTimeline
80    )
81}
82
83#[cfg(test)]
84mod tests {
85    use super::*;
86
87    #[test]
88    fn on_time_pass() {
89        let g = check_temporal_window(TemporalWindow::default(), Some(400), Some(1200), 1200);
90        assert_eq!(g, TemporalGate::Ok);
91    }
92
93    #[test]
94    fn late_start_fails() {
95        let g = check_temporal_window(TemporalWindow::default(), Some(900), Some(1500), 1500);
96        assert_eq!(g, TemporalGate::TimeToStartExceeded);
97    }
98
99    #[test]
100    fn never_complete_by_ttc_fails() {
101        let g = check_temporal_window(TemporalWindow::default(), Some(200), None, 2100);
102        assert_eq!(g, TemporalGate::TimeToCompleteExceeded);
103    }
104
105    #[test]
106    fn still_inside_tts_ok() {
107        let g = check_temporal_window(TemporalWindow::default(), None, None, 500);
108        assert_eq!(g, TemporalGate::Ok);
109    }
110}