Skip to main content

qualia_core_db/net/qdnf/biometrics/
capture.rs

1//! Raw biometric capture (E15.1). Ephemeral, modality-specific, local.
2//!
3//! Raw samples stay with the caller. This record holds only acquisition
4//! metadata. It is not a network identifier and is not a template.
5
6use crate::net::qdnf::errors::QdnfError;
7use crate::net::qdnf::types::StrongDigest;
8
9use super::BiometricObjectKind;
10
11/// Distinct acquisition kinds. Do not collapse these into one generic hash.
12#[repr(u8)]
13#[derive(Clone, Copy, Debug, PartialEq, Eq)]
14pub enum Modality {
15    Face = 1,
16    Voice = 2,
17    Iris = 3,
18    Fingerprint = 4,
19    Gait = 5,
20    Medical = 6,
21}
22
23impl Modality {
24    /// Builds `Modality` from `wire`.
25    pub fn from_wire(value: u8) -> Result<Self, QdnfError> {
26        match value {
27            1 => Ok(Self::Face),
28            2 => Ok(Self::Voice),
29            3 => Ok(Self::Iris),
30            4 => Ok(Self::Fingerprint),
31            5 => Ok(Self::Gait),
32            6 => Ok(Self::Medical),
33            _ => Err(QdnfError::Malformed),
34        }
35    }
36
37    #[inline]
38    /// Wire byte for the modality.
39    pub const fn to_wire(self) -> u8 {
40        self as u8
41    }
42}
43
44/// Acquisition metadata. Sample bytes are never stored here.
45#[repr(C)]
46#[derive(Clone, Copy, Debug, PartialEq, Eq)]
47pub struct RawCapture {
48    modality: Modality,
49    device: StrongDigest,
50    consent: StrongDigest,
51    quality: u16,
52    timestamp_uncertainty: u16,
53}
54
55impl RawCapture {
56    /// Acquires the resource.
57    pub fn acquire(
58        modality: Modality,
59        device: StrongDigest,
60        consent: StrongDigest,
61        quality: u16,
62        timestamp_uncertainty: u16,
63    ) -> Result<Self, QdnfError> {
64        if device.is_zero() || consent.is_zero() {
65            return Err(QdnfError::Malformed);
66        }
67        if quality == 0 {
68            return Err(QdnfError::Incomplete);
69        }
70        Ok(Self {
71            modality,
72            device,
73            consent,
74            quality,
75            timestamp_uncertainty,
76        })
77    }
78
79    #[inline]
80    /// Biometric object kind.
81    pub const fn kind(self) -> BiometricObjectKind {
82        BiometricObjectKind::RawCapture
83    }
84
85    #[inline]
86    /// Modality.
87    pub const fn modality(self) -> Modality {
88        self.modality
89    }
90
91    #[inline]
92    /// Device digest.
93    pub const fn device(self) -> StrongDigest {
94        self.device
95    }
96
97    #[inline]
98    /// Consent digest.
99    pub const fn consent(self) -> StrongDigest {
100        self.consent
101    }
102
103    #[inline]
104    /// Capture quality.
105    pub const fn quality(self) -> u16 {
106        self.quality
107    }
108
109    #[inline]
110    /// Timestamp uncertainty.
111    pub const fn timestamp_uncertainty(self) -> u16 {
112        self.timestamp_uncertainty
113    }
114}
115
116/// A raw capture is not a QDNF routing or session identifier.
117pub fn retain_raw_as_network_id(_capture: &RawCapture) -> Result<(), QdnfError> {
118    Err(QdnfError::Denied)
119}
120
121#[cfg(test)]
122mod tests {
123    use super::*;
124
125    fn d(tag: u8) -> StrongDigest {
126        let mut x = StrongDigest::ZERO;
127        x.0[0] = tag;
128        x.0[47] = 0xC1;
129        x
130    }
131
132    #[test]
133    fn acquire_requires_device_consent_and_quality() {
134        assert_eq!(
135            RawCapture::acquire(Modality::Face, StrongDigest::ZERO, d(2), 10, 1).unwrap_err(),
136            QdnfError::Malformed
137        );
138        assert_eq!(
139            RawCapture::acquire(Modality::Face, d(1), StrongDigest::ZERO, 10, 1).unwrap_err(),
140            QdnfError::Malformed
141        );
142        assert_eq!(
143            RawCapture::acquire(Modality::Iris, d(1), d(2), 0, 1).unwrap_err(),
144            QdnfError::Incomplete
145        );
146        let c = RawCapture::acquire(Modality::Voice, d(1), d(2), 12, 3).unwrap();
147        assert_eq!(c.kind(), BiometricObjectKind::RawCapture);
148        assert_eq!(c.modality(), Modality::Voice);
149        assert_eq!(c.quality(), 12);
150    }
151
152    #[test]
153    fn modalities_are_not_one_generic_hash() {
154        assert_ne!(Modality::Face.to_wire(), Modality::Fingerprint.to_wire());
155        assert_ne!(Modality::Voice.to_wire(), Modality::Medical.to_wire());
156        assert_eq!(Modality::from_wire(0).unwrap_err(), QdnfError::Malformed);
157        assert_eq!(Modality::from_wire(4).unwrap(), Modality::Fingerprint);
158    }
159
160    #[test]
161    fn raw_capture_is_not_a_network_id() {
162        let c = RawCapture::acquire(Modality::Gait, d(3), d(4), 8, 0).unwrap();
163        assert_eq!(retain_raw_as_network_id(&c).unwrap_err(), QdnfError::Denied);
164    }
165}