Skip to main content

qualia_core_db/net/qdnf/session/
freshness.rs

1//! Recheck policy freshness at queued, offline, and migration (NET-05.18).
2//!
3//! A cached [`PolicyOutcome::Allow`] is not sufficient after queue, offline, or
4//! migration. Sensitive work stays pending until a fresh Allow with a current
5//! grant. A separately authorized help/accessibility path remains available while
6//! sensitive work is pending. Blocked and Suspended contacts stay Denied;
7//! payment cannot bypass. Packages remain open.
8
9use crate::net::qdnf::authority::{ContactState, PolicyOutcome};
10use crate::net::qdnf::errors::QdnfError;
11use crate::net::qdnf::session::policy::gate_channel;
12use crate::net::qdnf::types::OperationId;
13
14/// Occupied sensitive-pending slots. A 17th distinct pending id is Capacity.
15pub const MAX_PENDING: usize = 16;
16
17/// Why admission must recheck protective policy and grant freshness.
18#[repr(u8)]
19#[derive(Clone, Copy, Debug, PartialEq, Eq)]
20pub enum RecheckReason {
21    Queued = 1,
22    Offline = 2,
23    Migration = 3,
24}
25
26/// Result of a freshness recheck. Sensitive pending is not a help-path error.
27#[repr(u8)]
28#[derive(Clone, Copy, Debug, PartialEq, Eq)]
29pub enum FreshnessVerdict {
30    Admitted = 1,
31    /// Sensitive stays pending until a fresh Allow with a current grant.
32    SensitivePending = 2,
33}
34
35#[repr(C)]
36#[derive(Clone, Copy, Debug, PartialEq, Eq)]
37struct PendingSlot {
38    id: OperationId,
39    reason: RecheckReason,
40}
41
42/// Sixteen-slot table of sensitive work waiting on a fresh current grant.
43pub struct FreshnessTable {
44    slots: [Option<PendingSlot>; MAX_PENDING],
45}
46
47impl FreshnessTable {
48    /// Creates a default `FreshnessTable`.
49    pub const fn new() -> Self {
50        Self {
51            slots: [None; MAX_PENDING],
52        }
53    }
54
55    fn insert_pending(&mut self, id: OperationId, reason: RecheckReason) -> Result<(), QdnfError> {
56        let mut free = None;
57        let mut i = 0usize;
58        while i < MAX_PENDING {
59            match self.slots[i] {
60                Some(slot) if slot.id == id => {
61                    self.slots[i] = Some(PendingSlot { id, reason });
62                    return Ok(());
63                }
64                Some(_) => {}
65                None => {
66                    if free.is_none() {
67                        free = Some(i);
68                    }
69                }
70            }
71            i += 1;
72        }
73        let idx = free.ok_or(QdnfError::Capacity)?;
74        self.slots[idx] = Some(PendingSlot { id, reason });
75        Ok(())
76    }
77
78    fn clear(&mut self, id: OperationId) {
79        let mut i = 0usize;
80        while i < MAX_PENDING {
81            if let Some(slot) = self.slots[i] {
82                if slot.id == id {
83                    self.slots[i] = None;
84                    return;
85                }
86            }
87            i += 1;
88        }
89    }
90}
91
92impl Default for FreshnessTable {
93    fn default() -> Self {
94        Self::new()
95    }
96}
97
98/// Cached Allow never skips a queued / offline / migration recheck.
99#[inline]
100pub fn cached_allow_skips_recheck() -> bool {
101    false
102}
103
104/// Help/accessibility remains available while sensitive work is pending.
105#[inline]
106pub fn help_accessible_while_sensitive_pending() -> bool {
107    true
108}
109
110/// Admit or re-admit after queued, offline, or migration.
111///
112/// Cached Allow without a current grant is insufficient ([`QdnfError::Incomplete`]
113/// when not sensitive). Sensitive work that is not a fresh current Allow stays
114/// [`FreshnessVerdict::SensitivePending`] unless contact is Blocked/Suspended or
115/// the outcome is Deny.
116pub fn recheck(
117    table: &mut FreshnessTable,
118    id: OperationId,
119    reason: RecheckReason,
120    outcome: PolicyOutcome,
121    grant_current: bool,
122    contact: ContactState,
123    sensitive: bool,
124) -> Result<FreshnessVerdict, QdnfError> {
125    if id == OperationId::ZERO {
126        return Err(QdnfError::Malformed);
127    }
128
129    // Queued, offline, and migration always require a live recheck.
130    let _ = reason;
131    debug_assert!(!cached_allow_skips_recheck());
132
133    if matches!(contact, ContactState::Blocked | ContactState::Suspended) {
134        return Err(QdnfError::Denied);
135    }
136
137    if outcome == PolicyOutcome::Deny {
138        table.clear(id);
139        return Err(QdnfError::Denied);
140    }
141
142    let current_allow = outcome == PolicyOutcome::Allow && grant_current;
143
144    if sensitive && !current_allow {
145        table.insert_pending(id, reason)?;
146        return Ok(FreshnessVerdict::SensitivePending);
147    }
148
149    if !current_allow {
150        if outcome == PolicyOutcome::Allow {
151            return Err(QdnfError::Incomplete);
152        }
153        return Err(match gate_channel(outcome, grant_current, contact) {
154            Ok(()) => QdnfError::Unauthorized,
155            Err(e) => e,
156        });
157    }
158
159    table.clear(id);
160    gate_channel(outcome, grant_current, contact)?;
161    Ok(FreshnessVerdict::Admitted)
162}
163
164#[cfg(test)]
165mod tests {
166    use super::*;
167
168    fn operation(tag: u8) -> OperationId {
169        let mut id = OperationId::ZERO;
170        id.0[0] = tag;
171        id
172    }
173
174    #[test]
175    fn queued_cached_allow_without_current_grant_is_insufficient() {
176        let mut table = FreshnessTable::new();
177        assert_eq!(
178            recheck(
179                &mut table,
180                operation(1),
181                RecheckReason::Queued,
182                PolicyOutcome::Allow,
183                false,
184                ContactState::Active,
185                false,
186            ),
187            Err(QdnfError::Incomplete)
188        );
189        assert_eq!(
190            recheck(
191                &mut table,
192                operation(2),
193                RecheckReason::Queued,
194                PolicyOutcome::Allow,
195                false,
196                ContactState::Active,
197                true,
198            ),
199            Ok(FreshnessVerdict::SensitivePending)
200        );
201    }
202
203    #[test]
204    fn offline_fresh_allow_current_grant_not_sensitive_is_admitted() {
205        let mut table = FreshnessTable::new();
206        assert_eq!(
207            recheck(
208                &mut table,
209                operation(3),
210                RecheckReason::Offline,
211                PolicyOutcome::Allow,
212                true,
213                ContactState::Active,
214                false,
215            ),
216            Ok(FreshnessVerdict::Admitted)
217        );
218    }
219
220    #[test]
221    fn migration_deny_is_denied() {
222        let mut table = FreshnessTable::new();
223        assert_eq!(
224            recheck(
225                &mut table,
226                operation(4),
227                RecheckReason::Migration,
228                PolicyOutcome::Deny,
229                true,
230                ContactState::Active,
231                false,
232            ),
233            Err(QdnfError::Denied)
234        );
235        assert_eq!(
236            recheck(
237                &mut table,
238                operation(5),
239                RecheckReason::Migration,
240                PolicyOutcome::Deny,
241                true,
242                ContactState::Active,
243                true,
244            ),
245            Err(QdnfError::Denied)
246        );
247    }
248
249    #[test]
250    fn blocked_cannot_pay_to_bypass() {
251        let mut table = FreshnessTable::new();
252        assert_eq!(
253            recheck(
254                &mut table,
255                operation(6),
256                RecheckReason::Queued,
257                PolicyOutcome::Allow,
258                true,
259                ContactState::Blocked,
260                false,
261            ),
262            Err(QdnfError::Denied)
263        );
264        assert_eq!(
265            recheck(
266                &mut table,
267                operation(7),
268                RecheckReason::Offline,
269                PolicyOutcome::Allow,
270                true,
271                ContactState::Blocked,
272                true,
273            ),
274            Err(QdnfError::Denied)
275        );
276        assert_eq!(
277            recheck(
278                &mut table,
279                operation(8),
280                RecheckReason::Migration,
281                PolicyOutcome::Allow,
282                true,
283                ContactState::Suspended,
284                false,
285            ),
286            Err(QdnfError::Denied)
287        );
288    }
289
290    #[test]
291    fn sensitive_pending_does_not_block_help_admit() {
292        let mut table = FreshnessTable::new();
293        assert_eq!(
294            recheck(
295                &mut table,
296                operation(9),
297                RecheckReason::Queued,
298                PolicyOutcome::Allow,
299                false,
300                ContactState::Active,
301                true,
302            ),
303            Ok(FreshnessVerdict::SensitivePending)
304        );
305        assert_eq!(
306            recheck(
307                &mut table,
308                operation(10),
309                RecheckReason::Queued,
310                PolicyOutcome::Allow,
311                true,
312                ContactState::Active,
313                false,
314            ),
315            Ok(FreshnessVerdict::Admitted)
316        );
317        assert!(help_accessible_while_sensitive_pending());
318    }
319
320    #[test]
321    fn help_accessible_while_sensitive_pending_is_true() {
322        assert!(help_accessible_while_sensitive_pending());
323    }
324
325    #[test]
326    fn cached_allow_does_not_skip_recheck() {
327        assert!(!cached_allow_skips_recheck());
328    }
329
330    #[test]
331    fn seventeenth_pending_sensitive_is_capacity() {
332        let mut table = FreshnessTable::new();
333        let mut n = 1u8;
334        while n <= MAX_PENDING as u8 {
335            assert_eq!(
336                recheck(
337                    &mut table,
338                    operation(n),
339                    RecheckReason::Offline,
340                    PolicyOutcome::Allow,
341                    false,
342                    ContactState::Active,
343                    true,
344                ),
345                Ok(FreshnessVerdict::SensitivePending)
346            );
347            n += 1;
348        }
349        assert_eq!(
350            recheck(
351                &mut table,
352                operation(MAX_PENDING as u8),
353                RecheckReason::Queued,
354                PolicyOutcome::Incomplete,
355                false,
356                ContactState::Active,
357                true,
358            ),
359            Ok(FreshnessVerdict::SensitivePending)
360        );
361        assert_eq!(
362            recheck(
363                &mut table,
364                operation(0x20),
365                RecheckReason::Migration,
366                PolicyOutcome::Allow,
367                false,
368                ContactState::Active,
369                true,
370            ),
371            Err(QdnfError::Capacity)
372        );
373    }
374
375    #[test]
376    fn zero_operation_is_malformed() {
377        let mut table = FreshnessTable::new();
378        assert_eq!(
379            recheck(
380                &mut table,
381                OperationId::ZERO,
382                RecheckReason::Queued,
383                PolicyOutcome::Allow,
384                true,
385                ContactState::Active,
386                false,
387            ),
388            Err(QdnfError::Malformed)
389        );
390    }
391}