Skip to main content

qualia_core_db/net/qdnf/authority/
permit.rs

1//! Local execution permit. Capability for this runtime, not an identity claim.
2
3use crate::net::peer::runtime::incarnation::CanonicalIncarnation;
4use crate::net::qdnf::errors::QdnfError;
5use crate::net::qdnf::types::{Generation, OperationId, StrongDigest};
6
7use super::owner::MutationHandle;
8use super::policy::TemporalGrant;
9use super::verified::{AuthorisedContact, InstalledSessionKeys, VerifiedCredential};
10
11/// Compiled permit. Fields are private; only [`super::AuthorityOwner`] issues it.
12#[derive(Clone, Copy, Debug, PartialEq, Eq)]
13pub struct ExecutionPermit {
14    operation: OperationId,
15    principal: StrongDigest,
16    recipient: StrongDigest,
17    purpose: StrongDigest,
18    instrument: StrongDigest,
19    policy_generation: Generation,
20    identity_generation: Generation,
21    expires_unix: u64,
22    resource_ceiling: u64,
23    incarnation: CanonicalIncarnation,
24}
25
26impl ExecutionPermit {
27    /// Issues a permit binding contact+credential+grant+handle+keys.
28    pub(crate) fn issue(
29        operation: OperationId,
30        principal: StrongDigest,
31        recipient: StrongDigest,
32        purpose: StrongDigest,
33        instrument: StrongDigest,
34        policy_generation: Generation,
35        identity_generation: Generation,
36        expires_unix: u64,
37        resource_ceiling: u64,
38        incarnation: CanonicalIncarnation,
39    ) -> Result<Self, QdnfError> {
40        if operation.is_zero()
41            || principal.is_zero()
42            || recipient.is_zero()
43            || purpose.is_zero()
44            || instrument.is_zero()
45        {
46            return Err(QdnfError::Unauthorized);
47        }
48        if principal == recipient {
49            return Err(QdnfError::Conflict);
50        }
51        if policy_generation == Generation::ZERO || identity_generation == Generation::ZERO {
52            return Err(QdnfError::Unauthorized);
53        }
54        if !incarnation.assigned() {
55            return Err(QdnfError::StaleGeneration);
56        }
57        if resource_ceiling == 0 {
58            return Err(QdnfError::Capacity);
59        }
60        Ok(Self {
61            operation,
62            principal,
63            recipient,
64            purpose,
65            instrument,
66            policy_generation,
67            identity_generation,
68            expires_unix,
69            resource_ceiling,
70            incarnation,
71        })
72    }
73
74    pub(crate) const fn incarnation(self) -> CanonicalIncarnation {
75        self.incarnation
76    }
77
78    #[inline]
79    /// Operation ID.
80    pub const fn operation(self) -> OperationId {
81        self.operation
82    }
83
84    #[inline]
85    /// Principal digest.
86    pub const fn principal(self) -> StrongDigest {
87        self.principal
88    }
89
90    #[inline]
91    /// Recipient digest.
92    pub const fn recipient(self) -> StrongDigest {
93        self.recipient
94    }
95
96    #[inline]
97    /// Purpose digest.
98    pub const fn purpose(self) -> StrongDigest {
99        self.purpose
100    }
101
102    #[inline]
103    /// Instrument digest.
104    pub const fn instrument(self) -> StrongDigest {
105        self.instrument
106    }
107
108    #[inline]
109    /// Policy generation.
110    pub const fn policy_generation(self) -> Generation {
111        self.policy_generation
112    }
113
114    #[inline]
115    /// Identity generation.
116    pub const fn identity_generation(self) -> Generation {
117        self.identity_generation
118    }
119
120    #[inline]
121    /// Expiry epoch.
122    pub const fn expires_unix(self) -> u64 {
123        self.expires_unix
124    }
125
126    #[inline]
127    /// Resource ceiling.
128    pub const fn resource_ceiling(self) -> u64 {
129        self.resource_ceiling
130    }
131
132    /// `Ok(())` when the permit is current at `now_unix`.
133    pub fn current_at(&self, now_unix: u64) -> Result<(), QdnfError> {
134        if now_unix >= self.expires_unix {
135            Err(QdnfError::Expired)
136        } else {
137            Ok(())
138        }
139    }
140
141    /// `Ok` when `contact` matches the permitted contact; `QdnfError` otherwise.
142    pub fn matches_contact(&self, contact: &AuthorisedContact) -> Result<(), QdnfError> {
143        contact.require_active()?;
144        if self.principal != contact.local() || self.recipient != contact.remote() {
145            return Err(QdnfError::Unauthorized);
146        }
147        Ok(())
148    }
149
150    /// `Ok` when `cred` matches the permitted credential.
151    pub fn matches_credential(&self, cred: &VerifiedCredential) -> Result<(), QdnfError> {
152        if self.principal != cred.principal() || self.instrument != cred.instrument() {
153            return Err(QdnfError::Unauthorized);
154        }
155        if self.identity_generation != cred.generation() {
156            return Err(QdnfError::StaleGeneration);
157        }
158        Ok(())
159    }
160
161    /// `Ok` when `grant` is within the permit's temporal window at `now_unix`.
162    pub fn matches_grant(&self, grant: &TemporalGrant, now_unix: u64) -> Result<(), QdnfError> {
163        grant.current_at(now_unix)?;
164        if grant.purpose_digest != self.purpose || grant.audience_digest != self.recipient {
165            return Err(QdnfError::Unauthorized);
166        }
167        Ok(())
168    }
169
170    /// `Ok` when `handle` matches the permitted mutation handle.
171    pub fn matches_handle(&self, handle: &MutationHandle) -> Result<(), QdnfError> {
172        handle.matches_permit(self)
173    }
174
175    /// `Ok` when `keys` satisfy the permit's session-key requirement.
176    pub fn require_keys(&self, keys: &InstalledSessionKeys) -> Result<(), QdnfError> {
177        if !keys.confirmed() {
178            return Err(QdnfError::Unauthorized);
179        }
180        Ok(())
181    }
182}
183
184#[cfg(test)]
185mod tests {
186    use super::*;
187
188    #[test]
189    fn expired_permit_is_rejected() {
190        let p = ExecutionPermit::issue(
191            OperationId([1u8; 16]),
192            StrongDigest([1u8; 48]),
193            StrongDigest([2u8; 48]),
194            StrongDigest([3u8; 48]),
195            StrongDigest([4u8; 48]),
196            Generation(1),
197            Generation(1),
198            10,
199            256,
200            CanonicalIncarnation::fresh().unwrap(),
201        )
202        .unwrap();
203        assert_eq!(p.current_at(10), Err(QdnfError::Expired));
204        assert!(p.current_at(9).is_ok());
205    }
206}