Skip to main content

qualia_core_db/net/qdnf/session/
fetch.rs

1//! Unconsented attachment/embed/LIG fetches must not disclose locators (NET-05.19).
2//!
3//! Group membership and payment are not private-message consent. `authorize_fetch`
4//! never writes locator bytes. Reveal is a second step and copies only an
5//! adapter-observed [`ObservedLocator`] after a valid [`FetchHandle`]. Packages
6//! remain open.
7
8use crate::net::qdnf::authority::{ContactState, PolicyOutcome};
9use crate::net::qdnf::errors::QdnfError;
10use crate::net::qdnf::session::policy::gate_channel;
11use crate::net::qdnf::types::ObservedLocator;
12
13/// Private token that `authorize_fetch` stamps into a live handle.
14const HANDLE_MAGIC: u64 = 0x5144_4E46_0519;
15
16/// Attachment, embed, and LIG fetches share the same private-consent gate.
17#[repr(u8)]
18#[derive(Clone, Copy, Debug, PartialEq, Eq)]
19pub enum FetchKind {
20    Attachment = 1,
21    Embed = 2,
22    Lig = 3,
23}
24
25/// Fetch intent. `group_member` and `paid` cannot substitute for `private_consent`.
26#[repr(C)]
27#[derive(Clone, Copy, Debug, PartialEq, Eq)]
28pub struct FetchRequest {
29    pub kind: FetchKind,
30    pub group_member: bool,
31    pub private_consent: bool,
32    pub paid: bool,
33}
34
35/// Capability token issued only after consent and Allow-equivalent contact.
36///
37/// Fields are private so callers cannot mint a valid handle. Zero/default is
38/// invalid and must not reveal.
39#[repr(C)]
40#[derive(Clone, Copy, Debug, PartialEq, Eq)]
41pub struct FetchHandle {
42    magic: u64,
43    kind: FetchKind,
44}
45
46impl FetchHandle {
47    /// Never authorizes reveal.
48    pub const INVALID: Self = Self {
49        magic: 0,
50        kind: FetchKind::Attachment,
51    };
52
53    #[inline]
54    const fn issue(kind: FetchKind) -> Self {
55        Self {
56            magic: HANDLE_MAGIC,
57            kind,
58        }
59    }
60
61    #[inline]
62    const fn is_valid(self) -> bool {
63        self.magic == HANDLE_MAGIC
64    }
65
66    /// Kind recorded at authorize time. Meaningless on [`FetchHandle::INVALID`].
67    #[inline]
68    pub const fn kind(self) -> FetchKind {
69        self.kind
70    }
71}
72
73/// Group admission is not private-message consent.
74#[inline]
75pub fn group_admission_implies_private_consent() -> bool {
76    false
77}
78
79/// Unconsented fetch must not copy locator or location bytes into caller buffers.
80#[inline]
81pub fn unconsented_fetch_discloses_locator() -> bool {
82    false
83}
84
85fn contact_is_allow_equivalent(contact: ContactState) -> bool {
86    matches!(contact, ContactState::Active | ContactState::Consent)
87}
88
89/// Authorize an attachment/embed/LIG fetch. Never writes `out_locator`.
90///
91/// Denied/Unauthorized leave `out_locator` untouched. Success returns a
92/// [`FetchHandle`]; the caller must pass an adapter-observed locator to
93/// [`reveal_observed`] afterwards. Destination locators are never taken from
94/// payload claims.
95pub fn authorize_fetch(
96    req: FetchRequest,
97    contact: ContactState,
98    out_locator: &mut ObservedLocator,
99) -> Result<FetchHandle, QdnfError> {
100    // Caller owns this buffer. Deny and Ok both leave it unchanged so a
101    // partial write cannot become a locator/location oracle.
102    let _untouched = out_locator;
103
104    let FetchRequest {
105        kind,
106        group_member,
107        private_consent,
108        paid,
109    } = req;
110    // Group membership and payment are not private-message consent.
111    let _ = (group_member, paid, kind);
112
113    if matches!(contact, ContactState::Blocked | ContactState::Suspended) {
114        return Err(QdnfError::Denied);
115    }
116    if !private_consent {
117        return Err(QdnfError::Denied);
118    }
119    if !contact_is_allow_equivalent(contact) {
120        return Err(QdnfError::Unauthorized);
121    }
122    gate_channel(PolicyOutcome::Allow, true, contact)?;
123    debug_assert!(!group_admission_implies_private_consent());
124    debug_assert!(!unconsented_fetch_discloses_locator());
125    Ok(FetchHandle::issue(kind))
126}
127
128/// Copy `src` into `out` only after a valid handle. Invalid handle: `out` unchanged.
129pub fn reveal_observed(
130    handle: FetchHandle,
131    src: ObservedLocator,
132    out: &mut ObservedLocator,
133) -> Result<(), QdnfError> {
134    if !handle.is_valid() {
135        return Err(QdnfError::Unauthorized);
136    }
137    *out = src;
138    Ok(())
139}
140
141/// Same as [`reveal_observed`]. Reveal is never combined with authorize.
142#[inline]
143pub fn reveal_locator(
144    handle: FetchHandle,
145    src: ObservedLocator,
146    out: &mut ObservedLocator,
147) -> Result<(), QdnfError> {
148    reveal_observed(handle, src, out)
149}
150
151#[cfg(test)]
152mod tests {
153    use super::*;
154
155    fn loc(tag: u8) -> ObservedLocator {
156        ObservedLocator::from_slice(&[tag, 0x11, 0x22, 0x33]).expect("locator")
157    }
158
159    fn req(kind: FetchKind, group_member: bool, private_consent: bool, paid: bool) -> FetchRequest {
160        FetchRequest {
161            kind,
162            group_member,
163            private_consent,
164            paid,
165        }
166    }
167
168    fn assert_untouched(before: ObservedLocator, after: &ObservedLocator) {
169        assert_eq!(*after, before);
170        assert!(!QdnfError::Denied.output_valid());
171        assert!(!QdnfError::Unauthorized.output_valid());
172    }
173
174    #[test]
175    fn unconsented_attachment_denied_out_remains_empty() {
176        let mut out = ObservedLocator::EMPTY;
177        let err = authorize_fetch(
178            req(FetchKind::Attachment, false, false, false),
179            ContactState::Active,
180            &mut out,
181        );
182        assert_eq!(err, Err(QdnfError::Denied));
183        assert_eq!(out, ObservedLocator::EMPTY);
184        assert!(!unconsented_fetch_discloses_locator());
185    }
186
187    #[test]
188    fn unconsented_embed_and_lig_denied_out_remains_empty() {
189        let mut embed_out = ObservedLocator::EMPTY;
190        assert_eq!(
191            authorize_fetch(
192                req(FetchKind::Embed, false, false, false),
193                ContactState::Consent,
194                &mut embed_out,
195            ),
196            Err(QdnfError::Denied)
197        );
198        assert_eq!(embed_out, ObservedLocator::EMPTY);
199
200        let mut lig_out = ObservedLocator::EMPTY;
201        assert_eq!(
202            authorize_fetch(
203                req(FetchKind::Lig, false, false, false),
204                ContactState::Active,
205                &mut lig_out,
206            ),
207            Err(QdnfError::Denied)
208        );
209        assert_eq!(lig_out, ObservedLocator::EMPTY);
210    }
211
212    #[test]
213    fn group_member_and_paid_do_not_disclose() {
214        let mut out = ObservedLocator::EMPTY;
215        assert_eq!(
216            authorize_fetch(
217                req(FetchKind::Attachment, true, false, true),
218                ContactState::Active,
219                &mut out,
220            ),
221            Err(QdnfError::Denied)
222        );
223        assert_eq!(out, ObservedLocator::EMPTY);
224        assert!(!group_admission_implies_private_consent());
225
226        let mut poison = loc(0xAA);
227        let before = poison;
228        assert_eq!(
229            authorize_fetch(
230                req(FetchKind::Embed, true, false, true),
231                ContactState::Consent,
232                &mut poison,
233            ),
234            Err(QdnfError::Denied)
235        );
236        assert_untouched(before, &poison);
237        assert_eq!(
238            reveal_observed(FetchHandle::INVALID, loc(0xBB), &mut poison),
239            Err(QdnfError::Unauthorized)
240        );
241        assert_untouched(before, &poison);
242    }
243
244    #[test]
245    fn consented_active_reveals_observed_locator_copy() {
246        let mut out = ObservedLocator::EMPTY;
247        let handle = authorize_fetch(
248            req(FetchKind::Attachment, false, true, false),
249            ContactState::Active,
250            &mut out,
251        )
252        .expect("consented active");
253        assert_eq!(out, ObservedLocator::EMPTY);
254        assert!(handle.is_valid());
255        assert_eq!(handle.kind(), FetchKind::Attachment);
256
257        let src = loc(0x42);
258        reveal_observed(handle, src, &mut out).expect("reveal");
259        assert_eq!(out, src);
260        assert_eq!(out.as_slice(), src.as_slice());
261
262        let mut consent_out = ObservedLocator::EMPTY;
263        let consent_handle = authorize_fetch(
264            req(FetchKind::Lig, true, true, true),
265            ContactState::Consent,
266            &mut consent_out,
267        )
268        .expect("consented contact");
269        assert_eq!(consent_out, ObservedLocator::EMPTY);
270        reveal_locator(consent_handle, loc(0x7E), &mut consent_out).expect("reveal_locator");
271        assert_eq!(consent_out, loc(0x7E));
272    }
273
274    #[test]
275    fn blocked_with_private_consent_denied() {
276        let mut out = loc(0xCC);
277        let before = out;
278        assert_eq!(
279            authorize_fetch(
280                req(FetchKind::Attachment, true, true, true),
281                ContactState::Blocked,
282                &mut out,
283            ),
284            Err(QdnfError::Denied)
285        );
286        assert_untouched(before, &out);
287
288        assert_eq!(
289            authorize_fetch(
290                req(FetchKind::Embed, false, true, false),
291                ContactState::Suspended,
292                &mut out,
293            ),
294            Err(QdnfError::Denied)
295        );
296        assert_untouched(before, &out);
297    }
298
299    #[test]
300    fn invalid_handle_does_not_write() {
301        let mut out = loc(0xDD);
302        let before = out;
303        assert_eq!(
304            reveal_observed(FetchHandle::INVALID, loc(0xEE), &mut out),
305            Err(QdnfError::Unauthorized)
306        );
307        assert_untouched(before, &out);
308        assert_eq!(
309            reveal_locator(FetchHandle::INVALID, loc(0xFF), &mut out),
310            Err(QdnfError::Unauthorized)
311        );
312        assert_untouched(before, &out);
313
314        let forged = FetchHandle {
315            magic: HANDLE_MAGIC ^ 1,
316            kind: FetchKind::Lig,
317        };
318        assert_eq!(
319            reveal_observed(forged, loc(0x01), &mut out),
320            Err(QdnfError::Unauthorized)
321        );
322        assert_untouched(before, &out);
323    }
324
325    #[test]
326    fn honest_fns_are_false() {
327        assert!(!group_admission_implies_private_consent());
328        assert!(!unconsented_fetch_discloses_locator());
329    }
330}