Skip to main content

qualia_core_db/net/qdnf/biometrics/
match_local.rs

1//! Device-local matching (E15.1, E15.2). Default path.
2//!
3//! QDNF records a platform authenticator decision bound to a cancellable
4//! template. It does not expose template bytes to the network and does not
5//! treat a match as an [`crate::net::qdnf::authority::ExecutionPermit`].
6
7use crate::net::qdnf::authority::ExecutionPermit;
8use crate::net::qdnf::errors::QdnfError;
9use crate::net::qdnf::types::StrongDigest;
10
11use super::capture::RawCapture;
12use super::template::DerivedTemplate;
13use super::BiometricObjectKind;
14
15/// Local comparison outcome. Sensitive derived data, not an authority grant.
16#[repr(u8)]
17#[derive(Clone, Copy, Debug, PartialEq, Eq)]
18pub enum MatchDecision {
19    NoMatch = 0,
20    Match = 1,
21}
22
23/// Score/decision plus uncertainty. Synthetic fixture scores are not FAR/FRR.
24#[repr(C)]
25#[derive(Clone, Copy, Debug, PartialEq, Eq)]
26pub struct MatchResult {
27    decision: MatchDecision,
28    score: u16,
29    uncertainty: u16,
30    quality: u16,
31    spoof_indicator: u16,
32    purpose: StrongDigest,
33    expires_unix: u64,
34}
35
36impl MatchResult {
37    #[inline]
38    /// Biometric object kind.
39    pub const fn kind(self) -> BiometricObjectKind {
40        BiometricObjectKind::MatchResult
41    }
42
43    #[inline]
44    /// Match decision.
45    pub const fn decision(self) -> MatchDecision {
46        self.decision
47    }
48
49    #[inline]
50    /// Match score.
51    pub const fn score(self) -> u16 {
52        self.score
53    }
54
55    #[inline]
56    /// Uncertainty margin.
57    pub const fn uncertainty(self) -> u16 {
58        self.uncertainty
59    }
60
61    #[inline]
62    /// Template quality.
63    pub const fn quality(self) -> u16 {
64        self.quality
65    }
66
67    #[inline]
68    /// Spoof indicator.
69    pub const fn spoof_indicator(self) -> u16 {
70        self.spoof_indicator
71    }
72
73    #[inline]
74    /// Purpose digest.
75    pub const fn purpose(self) -> StrongDigest {
76        self.purpose
77    }
78
79    #[inline]
80    /// Expiry epoch.
81    pub const fn expires_unix(self) -> u64 {
82        self.expires_unix
83    }
84
85    /// A match never grants session, routing, or identity privilege.
86    #[inline]
87    pub const fn grants_network_authority(self) -> bool {
88        false
89    }
90}
91
92/// Network authority is independent of biometric activation (NIST 800-63B).
93#[inline]
94pub const fn match_grants_network_authority() -> bool {
95    false
96}
97
98/// MatchResult cannot produce an execution permit. Always Denied.
99pub fn execution_permit_from_match(_result: &MatchResult) -> Result<ExecutionPermit, QdnfError> {
100    Err(QdnfError::Denied)
101}
102
103/// Default matcher: device-local, purpose-bound, non-revoked reference.
104///
105/// `platform_match` is the authenticator's local decision. The returned
106/// `score` is a protocol fixture (quality echo), not operational accuracy.
107pub fn match_local(
108    probe: &RawCapture,
109    reference: &DerivedTemplate,
110    platform_match: bool,
111    now_unix: u64,
112    expires_unix: u64,
113) -> Result<MatchResult, QdnfError> {
114    if reference.is_revoked() {
115        return Err(QdnfError::Revoked);
116    }
117    if probe.modality() != reference.modality() {
118        return Err(QdnfError::Conflict);
119    }
120    if now_unix >= expires_unix {
121        return Err(QdnfError::Expired);
122    }
123    let decision = if platform_match {
124        MatchDecision::Match
125    } else {
126        MatchDecision::NoMatch
127    };
128    Ok(MatchResult {
129        decision,
130        score: probe.quality(),
131        uncertainty: probe.timestamp_uncertainty(),
132        quality: probe.quality(),
133        spoof_indicator: 0,
134        purpose: reference.purpose(),
135        expires_unix,
136    })
137}
138
139#[cfg(test)]
140mod tests {
141    use super::*;
142    use crate::net::qdnf::biometrics::capture::Modality;
143    use crate::net::qdnf::biometrics::template::derive_template;
144    use crate::net::qdnf::types::Generation;
145
146    fn d(tag: u8) -> StrongDigest {
147        let mut x = StrongDigest::ZERO;
148        x.0[0] = tag;
149        x.0[47] = 0xC3;
150        x
151    }
152
153    fn probe() -> RawCapture {
154        RawCapture::acquire(Modality::Iris, d(1), d(2), 40, 2).unwrap()
155    }
156
157    fn reference() -> DerivedTemplate {
158        derive_template(&probe(), d(10), d(11), d(12), Generation(4)).unwrap()
159    }
160
161    #[test]
162    fn kinds_and_gates() {
163        let r = match_local(&probe(), &reference(), true, 1, 100).unwrap();
164        assert_eq!(r.kind(), BiometricObjectKind::MatchResult);
165        assert_eq!(r.decision(), MatchDecision::Match);
166        assert!(!match_grants_network_authority());
167        assert!(!r.grants_network_authority());
168    }
169
170    #[test]
171    fn successful_match_does_not_issue_execution_permit() {
172        let r = match_local(&probe(), &reference(), true, 1, 100).unwrap();
173        assert_eq!(
174            execution_permit_from_match(&r).unwrap_err(),
175            QdnfError::Denied
176        );
177    }
178
179    #[test]
180    fn no_match_is_still_not_authority() {
181        let r = match_local(&probe(), &reference(), false, 1, 100).unwrap();
182        assert_eq!(r.decision(), MatchDecision::NoMatch);
183        assert_eq!(
184            execution_permit_from_match(&r).unwrap_err(),
185            QdnfError::Denied
186        );
187    }
188
189    #[test]
190    fn revoked_reference_cannot_match() {
191        let mut t = reference();
192        crate::net::qdnf::biometrics::template::revoke_template(&mut t).unwrap();
193        assert_eq!(
194            match_local(&probe(), &t, true, 1, 100).unwrap_err(),
195            QdnfError::Revoked
196        );
197    }
198
199    #[test]
200    fn modality_mismatch_is_conflict() {
201        let voice = RawCapture::acquire(Modality::Voice, d(1), d(2), 40, 2).unwrap();
202        assert_eq!(
203            match_local(&voice, &reference(), true, 1, 100).unwrap_err(),
204            QdnfError::Conflict
205        );
206    }
207
208    #[test]
209    fn expired_window_is_expired() {
210        assert_eq!(
211            match_local(&probe(), &reference(), true, 100, 100).unwrap_err(),
212            QdnfError::Expired
213        );
214    }
215}