Skip to main content

qualia_core_db/net/qdnf/route/
validate.rs

1//! E08.1 — admit topology records only after origin/scope/sequence/expiry checks.
2
3use crate::crypto::network::digest::sha384;
4use crate::net::qdnf::errors::QdnfError;
5use crate::net::qdnf::types::StrongDigest;
6
7use super::index::{insert_edge, AdjacencyIndex};
8
9/// Handling profile P0..P3. Higher is stricter.
10pub const PROFILE_P0: u8 = 0;
11pub const PROFILE_P3: u8 = 3;
12
13/// Compact node id 0 is reserved (not a topology origin or endpoint).
14pub const MIN_COMPACT_NODE: u8 = 1;
15
16/// Untrusted topology advertisement. Digest is checked only when bytes are supplied.
17#[repr(C)]
18#[derive(Clone, Copy, Debug, PartialEq, Eq)]
19pub struct TopologyRecord {
20    pub origin: u8,
21    pub origin_digest: StrongDigest,
22    pub scope: u64,
23    pub from: u8,
24    pub to: u8,
25    pub sequence: u32,
26    pub expiry_unix: u64,
27    pub withdrawn: bool,
28    pub bidirectional: bool,
29    pub cost: u16,
30    pub latency_ms: u32,
31    pub energy_uj: u32,
32    pub energy_known: bool,
33    pub realm_bit: u8,
34    pub profile: u8,
35    pub failure_domain: u8,
36    pub digest: StrongDigest,
37}
38
39/// Edge that passed validation. Never a candidate while `withdrawn`.
40#[repr(C)]
41#[derive(Clone, Copy, Debug, PartialEq, Eq)]
42pub struct ValidatedEdge {
43    pub origin: u8,
44    pub from: u8,
45    pub to: u8,
46    pub sequence: u32,
47    pub expiry_unix: u64,
48    pub withdrawn: bool,
49    pub bidirectional: bool,
50    pub cost: u16,
51    pub latency_ms: u32,
52    pub energy_uj: u32,
53    pub energy_known: bool,
54    pub realm_bit: u8,
55    pub profile: u8,
56    pub failure_domain: u8,
57    pub scope: u64,
58}
59
60impl ValidatedEdge {
61    pub const EMPTY: Self = Self {
62        origin: 0,
63        from: 0,
64        to: 0,
65        sequence: 0,
66        expiry_unix: 0,
67        withdrawn: false,
68        bidirectional: false,
69        cost: 0,
70        latency_ms: 0,
71        energy_uj: 0,
72        energy_known: false,
73        realm_bit: 0,
74        profile: 0,
75        failure_domain: 0,
76        scope: 0,
77    };
78}
79
80fn compact_in_range(id: u8) -> bool {
81    id >= MIN_COMPACT_NODE
82}
83
84/// Validate `rec` against `expected_scope`, clock, per-origin sequence, and optional bytes.
85pub fn validate_record(
86    rec: &TopologyRecord,
87    expected_scope: u64,
88    now_unix: u64,
89    last_sequence: Option<u32>,
90    original_bytes: Option<&[u8]>,
91) -> Result<ValidatedEdge, QdnfError> {
92    if rec.origin == 0 || rec.origin_digest.is_zero() {
93        return Err(QdnfError::Range);
94    }
95    if !compact_in_range(rec.origin) {
96        return Err(QdnfError::Range);
97    }
98    if rec.scope != expected_scope {
99        return Err(QdnfError::Unauthorized);
100    }
101    if !compact_in_range(rec.from) || !compact_in_range(rec.to) {
102        return Err(QdnfError::Range);
103    }
104    if rec.from == rec.to {
105        return Err(QdnfError::Malformed);
106    }
107    if rec.realm_bit >= 64 {
108        return Err(QdnfError::Range);
109    }
110    if rec.profile > PROFILE_P3 {
111        return Err(QdnfError::UnknownProfile);
112    }
113    if now_unix >= rec.expiry_unix {
114        return Err(QdnfError::Expired);
115    }
116    if let Some(prev) = last_sequence {
117        if rec.sequence <= prev {
118            return Err(QdnfError::StaleGeneration);
119        }
120    }
121    if let Some(bytes) = original_bytes {
122        if bytes.is_empty() || rec.digest.is_zero() {
123            return Err(QdnfError::Malformed);
124        }
125        if sha384(bytes) != rec.digest {
126            return Err(QdnfError::Conflict);
127        }
128    }
129    Ok(ValidatedEdge {
130        origin: rec.origin,
131        from: rec.from,
132        to: rec.to,
133        sequence: rec.sequence,
134        expiry_unix: rec.expiry_unix,
135        withdrawn: rec.withdrawn,
136        bidirectional: rec.bidirectional,
137        cost: rec.cost,
138        latency_ms: rec.latency_ms,
139        energy_uj: rec.energy_uj,
140        energy_known: rec.energy_known,
141        realm_bit: rec.realm_bit,
142        profile: rec.profile,
143        failure_domain: rec.failure_domain,
144        scope: rec.scope,
145    })
146}
147
148/// Validate then insert. Never writes the index on failure.
149pub fn insert(
150    rec: &TopologyRecord,
151    expected_scope: u64,
152    now_unix: u64,
153    original_bytes: Option<&[u8]>,
154    index: &mut AdjacencyIndex,
155) -> Result<(), QdnfError> {
156    if index.scope() != expected_scope {
157        return Err(QdnfError::Unauthorized);
158    }
159    let last = index.last_sequence(rec.origin);
160    let edge = validate_record(rec, expected_scope, now_unix, last, original_bytes)?;
161    insert_edge(index, edge)
162}
163
164#[cfg(test)]
165mod tests {
166    use super::*;
167    use crate::crypto::network::digest::sha384;
168
169    /// `ValidatedEdge::rec`.
170    pub(crate) fn rec(origin: u8, from: u8, to: u8, seq: u32, expiry: u64) -> TopologyRecord {
171        TopologyRecord {
172            origin,
173            origin_digest: {
174                let mut d = StrongDigest::ZERO;
175                d.0[0] = origin;
176                d.0[47] = 1;
177                d
178            },
179            scope: 1,
180            from,
181            to,
182            sequence: seq,
183            expiry_unix: expiry,
184            withdrawn: false,
185            bidirectional: true,
186            cost: 1,
187            latency_ms: 1,
188            energy_uj: 1,
189            energy_known: true,
190            realm_bit: 0,
191            profile: PROFILE_P0,
192            failure_domain: origin,
193            digest: StrongDigest::ZERO,
194        }
195    }
196
197    #[test]
198    fn origin_zero_is_range() {
199        let r = rec(0, 1, 2, 1, 10);
200        assert_eq!(validate_record(&r, 1, 1, None, None), Err(QdnfError::Range));
201    }
202
203    #[test]
204    fn scope_mismatch_is_unauthorized() {
205        let r = rec(1, 1, 2, 1, 10);
206        assert_eq!(
207            validate_record(&r, 99, 1, None, None),
208            Err(QdnfError::Unauthorized)
209        );
210    }
211
212    #[test]
213    fn endpoint_zero_is_range() {
214        let r = rec(1, 0, 2, 1, 10);
215        assert_eq!(validate_record(&r, 1, 1, None, None), Err(QdnfError::Range));
216    }
217
218    #[test]
219    fn stale_sequence_is_rejected() {
220        let r = rec(1, 1, 2, 3, 10);
221        assert_eq!(
222            validate_record(&r, 1, 1, Some(3), None),
223            Err(QdnfError::StaleGeneration)
224        );
225        assert_eq!(
226            validate_record(&r, 1, 1, Some(4), None),
227            Err(QdnfError::StaleGeneration)
228        );
229        assert!(validate_record(&r, 1, 1, Some(2), None).is_ok());
230    }
231
232    #[test]
233    fn expired_record_is_rejected() {
234        let r = rec(1, 1, 2, 1, 10);
235        assert_eq!(
236            validate_record(&r, 1, 10, None, None),
237            Err(QdnfError::Expired)
238        );
239    }
240
241    #[test]
242    fn digest_mismatch_is_conflict() {
243        let mut r = rec(1, 1, 2, 1, 10);
244        r.digest = sha384(b"lsa-v1");
245        assert_eq!(
246            validate_record(&r, 1, 1, None, Some(b"tampered")),
247            Err(QdnfError::Conflict)
248        );
249        assert!(validate_record(&r, 1, 1, None, Some(b"lsa-v1")).is_ok());
250    }
251
252    #[test]
253    fn insert_happens_only_after_validation() {
254        let mut index = AdjacencyIndex::new(1);
255        let bad = rec(1, 1, 2, 1, 10);
256        assert_eq!(
257            insert(&bad, 2, 1, None, &mut index),
258            Err(QdnfError::Unauthorized)
259        );
260        assert_eq!(index.live_count(1), 0);
261        insert(&rec(1, 1, 2, 1, 10), 1, 1, None, &mut index).unwrap();
262        assert_eq!(index.live_count(1), 1);
263    }
264
265    #[test]
266    fn withdrawal_is_not_kept_as_candidate() {
267        let mut index = AdjacencyIndex::new(1);
268        insert(&rec(1, 1, 2, 1, 10), 1, 1, None, &mut index).unwrap();
269        let mut w = rec(1, 1, 2, 2, 10);
270        w.withdrawn = true;
271        insert(&w, 1, 1, None, &mut index).unwrap();
272        assert_eq!(index.live_count(1), 0);
273        assert!(index.is_withdrawn(1, 2));
274    }
275}