Skip to main content

qualia_core_db/net/qdnf/authority/
policy.rs

1//! Semantic and authority contracts (FND-02).
2//!
3//! Entity, claim, handle and instrument planes stay distinct. No universal
4//! NaturalAgent join key, reputation score, or authority from similarity, wallet
5//! possession or nominal signature count.
6
7use crate::net::qdnf::errors::QdnfError;
8use crate::net::qdnf::types::{ProfileId, StrongDigest};
9
10/// Identifier fabric planes. A verified route is not a NaturalAgent.
11#[repr(u8)]
12#[derive(Clone, Copy, Debug, PartialEq, Eq)]
13pub enum Plane {
14    Entity = 1,
15    Claim = 2,
16    Handle = 3,
17    Instrument = 4,
18}
19
20/// QPolicy decision. Only `Allow` with a current grant handle admits service traffic.
21#[repr(u8)]
22#[derive(Clone, Copy, Debug, PartialEq, Eq)]
23pub enum PolicyOutcome {
24    Allow = 1,
25    Deny = 2,
26    Challenge = 3,
27    NeedsHuman = 4,
28    Incomplete = 5,
29    Error = 6,
30}
31
32impl PolicyOutcome {
33    #[inline]
34    /// `PolicyOutcome::admits_service`.
35    pub const fn admits_service(self) -> bool {
36        matches!(self, Self::Allow)
37    }
38}
39
40/// Independent resource kinds. Energy, time and typed compute never mix.
41#[repr(u8)]
42#[derive(Clone, Copy, Debug, PartialEq, Eq)]
43pub enum ResourceKind {
44    EnergyJoules = 1,
45    TimeSeconds = 2,
46    TypedCompute = 3,
47}
48
49/// Observation quality. Unknown is not free or safe.
50#[repr(u8)]
51#[derive(Clone, Copy, Debug, PartialEq, Eq)]
52pub enum ObservationQuality {
53    Measured = 1,
54    Estimated = 2,
55    Unknown = 3,
56}
57
58/// Contributor / principal class for finite compensation.
59#[repr(u8)]
60#[derive(Clone, Copy, Debug, PartialEq, Eq)]
61pub enum CompensationClass {
62    Personal = 1,
63    Humanitarian = 2,
64    CorporateDelegated = 3,
65}
66
67/// Protected-person contact state. Payment cannot bypass these.
68#[repr(u8)]
69#[derive(Clone, Copy, Debug, PartialEq, Eq)]
70pub enum ContactState {
71    Request = 1,
72    Consent = 2,
73    Active = 3,
74    Suspended = 4,
75    Blocked = 5,
76}
77
78/// Independent facts that must not collapse into a trusted-peer boolean.
79#[repr(C)]
80#[derive(Clone, Copy, Debug, PartialEq, Eq)]
81pub struct IndependentFacts {
82    pub physically_reachable: bool,
83    pub transport_key_possessed: bool,
84    pub controller_authorized: bool,
85    pub relationship_exists: bool,
86    pub route_disclosable: bool,
87    pub operation_authorized: bool,
88}
89
90impl IndependentFacts {
91    pub const NONE: Self = Self {
92        physically_reachable: false,
93        transport_key_possessed: false,
94        controller_authorized: false,
95        relationship_exists: false,
96        route_disclosable: false,
97        operation_authorized: false,
98    };
99
100    pub const ALL: Self = Self {
101        physically_reachable: true,
102        transport_key_possessed: true,
103        controller_authorized: true,
104        relationship_exists: true,
105        route_disclosable: true,
106        operation_authorized: true,
107    };
108}
109
110/// Independent facts must not collapse into a trusted-peer boolean.
111#[inline]
112pub fn collapse_to_trusted_peer(_facts: IndependentFacts) -> Result<bool, QdnfError> {
113    Err(QdnfError::Denied)
114}
115
116/// Purpose-scoped grant. Cache hits never renew permission.
117#[repr(C)]
118#[derive(Clone, Copy, Debug, PartialEq, Eq)]
119pub struct TemporalGrant {
120    pub purpose_digest: StrongDigest,
121    pub audience_digest: StrongDigest,
122    pub authority_generation: u64,
123    pub not_before_unix: u64,
124    pub expires_unix: u64,
125    pub profile: ProfileId,
126}
127
128impl TemporalGrant {
129    /// Policy current at `unix_ts`.
130    pub fn current_at(&self, now_unix: u64) -> Result<(), QdnfError> {
131        if now_unix < self.not_before_unix {
132            return Err(QdnfError::Unauthorized);
133        }
134        if now_unix >= self.expires_unix {
135            return Err(QdnfError::Expired);
136        }
137        Ok(())
138    }
139}
140
141/// Cached view of a grant. `cached_at` is observational; it never extends expiry.
142#[repr(C)]
143#[derive(Clone, Copy, Debug, PartialEq, Eq)]
144pub struct CachedGrant {
145    pub stored: TemporalGrant,
146    pub cached_at: u64,
147}
148
149impl CachedGrant {
150    /// Uses the stored grant's `not_before` / `expires` clocks, not `cached_at`.
151    #[inline]
152    pub fn current_at(&self, now_unix: u64) -> Result<(), QdnfError> {
153        let _ = self.cached_at;
154        self.stored.current_at(now_unix)
155    }
156}
157
158/// Blocked/Revoked beat Allow. An expired historical grant cannot authorize now.
159#[inline]
160pub fn evaluate_precedence(
161    revoked: bool,
162    blocked: bool,
163    expired: bool,
164    allow: bool,
165) -> Result<(), QdnfError> {
166    if revoked {
167        return Err(QdnfError::Revoked);
168    }
169    if blocked {
170        return Err(QdnfError::Denied);
171    }
172    if expired {
173        return Err(QdnfError::Expired);
174    }
175    if allow {
176        Ok(())
177    } else {
178        Err(QdnfError::Unauthorized)
179    }
180}
181
182/// Bootstrap/control allowance is independent of payment. Paid cannot admit alone.
183#[inline]
184pub fn bootstrap_admit(paid: bool, control_allowance: bool) -> Result<(), QdnfError> {
185    let _ = paid;
186    if control_allowance {
187        Ok(())
188    } else {
189        Err(QdnfError::Denied)
190    }
191}
192
193/// Maps a policy outcome onto session admission.
194pub fn admit_service(outcome: PolicyOutcome, grant_current: bool) -> Result<(), QdnfError> {
195    match outcome {
196        PolicyOutcome::Allow if grant_current => Ok(()),
197        PolicyOutcome::Allow => Err(QdnfError::Expired),
198        PolicyOutcome::Deny => Err(QdnfError::Denied),
199        PolicyOutcome::Challenge => Err(QdnfError::Challenge),
200        PolicyOutcome::NeedsHuman => Err(QdnfError::NeedsHuman),
201        PolicyOutcome::Incomplete => Err(QdnfError::Incomplete),
202        PolicyOutcome::Error => Err(QdnfError::Unauthorized),
203    }
204}
205
206#[cfg(test)]
207mod tests {
208    use super::*;
209
210    #[test]
211    fn reachability_is_not_authorization() {
212        let mut facts = IndependentFacts::NONE;
213        facts.physically_reachable = true;
214        facts.transport_key_possessed = true;
215        assert!(!facts.operation_authorized);
216        assert!(!facts.controller_authorized);
217    }
218
219    #[test]
220    fn allow_without_current_grant_is_not_admission() {
221        assert_eq!(
222            admit_service(PolicyOutcome::Allow, false),
223            Err(QdnfError::Expired)
224        );
225        assert!(admit_service(PolicyOutcome::Allow, true).is_ok());
226    }
227
228    #[test]
229    fn payment_cannot_bypass_blocked_contact() {
230        assert_eq!(ContactState::Blocked as u8, 5);
231        assert!(!PolicyOutcome::Deny.admits_service());
232    }
233
234    fn grant_until(expires_unix: u64) -> TemporalGrant {
235        TemporalGrant {
236            purpose_digest: StrongDigest::ZERO,
237            audience_digest: StrongDigest::ZERO,
238            authority_generation: 1,
239            not_before_unix: 0,
240            expires_unix,
241            profile: ProfileId::QDNF_CRYPTO_1,
242        }
243    }
244
245    #[test]
246    fn collapse_to_trusted_peer_is_refused_even_when_all_facts_hold() {
247        assert_eq!(
248            collapse_to_trusted_peer(IndependentFacts::ALL),
249            Err(QdnfError::Denied)
250        );
251        assert_eq!(
252            collapse_to_trusted_peer(IndependentFacts::NONE),
253            Err(QdnfError::Denied)
254        );
255    }
256
257    #[test]
258    fn cache_hit_does_not_renew_expiry() {
259        let cached = CachedGrant {
260            stored: grant_until(100),
261            cached_at: 90,
262        };
263        assert!(cached.current_at(90).is_ok());
264        assert_eq!(cached.current_at(100), Err(QdnfError::Expired));
265        assert_eq!(cached.current_at(150), Err(QdnfError::Expired));
266        assert_eq!(cached.stored.expires_unix, 100);
267        assert_eq!(cached.cached_at, 90);
268    }
269
270    #[test]
271    fn cached_at_is_not_the_expiry_clock() {
272        let cached = CachedGrant {
273            stored: grant_until(50),
274            cached_at: 200,
275        };
276        assert_eq!(cached.current_at(40), Ok(()));
277        assert_eq!(cached.current_at(50), Err(QdnfError::Expired));
278        assert_eq!(cached.current_at(200), Err(QdnfError::Expired));
279    }
280
281    #[test]
282    fn revoked_beats_allow() {
283        assert_eq!(
284            evaluate_precedence(true, false, false, true),
285            Err(QdnfError::Revoked)
286        );
287    }
288
289    #[test]
290    fn blocked_beats_allow() {
291        assert_eq!(
292            evaluate_precedence(false, true, false, true),
293            Err(QdnfError::Denied)
294        );
295    }
296
297    #[test]
298    fn expired_historical_allow_cannot_authorize_current() {
299        assert_eq!(
300            evaluate_precedence(false, false, true, true),
301            Err(QdnfError::Expired)
302        );
303    }
304
305    #[test]
306    fn revoked_precedes_blocked_and_expired() {
307        assert_eq!(
308            evaluate_precedence(true, true, true, true),
309            Err(QdnfError::Revoked)
310        );
311        assert_eq!(
312            evaluate_precedence(false, true, true, true),
313            Err(QdnfError::Denied)
314        );
315    }
316
317    #[test]
318    fn current_allow_without_revocation_block_or_expiry() {
319        assert!(evaluate_precedence(false, false, false, true).is_ok());
320        assert_eq!(
321            evaluate_precedence(false, false, false, false),
322            Err(QdnfError::Unauthorized)
323        );
324    }
325
326    #[test]
327    fn payment_cannot_admit_without_control_allowance() {
328        assert_eq!(bootstrap_admit(true, false), Err(QdnfError::Denied));
329        assert!(bootstrap_admit(false, true).is_ok());
330        assert!(bootstrap_admit(true, true).is_ok());
331        assert_eq!(bootstrap_admit(false, false), Err(QdnfError::Denied));
332    }
333}