qualia_core_db/net/qdnf/fabric/
locator.rs1use crate::net::qdnf::errors::QdnfError;
10
11#[repr(u8)]
13#[derive(Clone, Copy, Debug, PartialEq, Eq)]
14pub enum AudienceScope {
15 PrivatePairwise = 1,
16 ClosedGroup = 2,
17 Community = 3,
18 PublicService = 4,
19}
20
21impl AudienceScope {
22 #[inline]
25 pub const fn can_publish_to_public_qsr(self) -> bool {
26 matches!(self, Self::PublicService)
27 }
28}
29
30#[repr(C)]
32#[derive(Clone, Copy, Debug, PartialEq, Eq)]
33pub struct RelationScopedLocator {
34 pub locator_hash: u64,
35 pub direction_hash: u64,
37 pub relation_context_hash: u64,
38 pub purpose_bind_hash: u64,
39 pub audience_scope: AudienceScope,
40 pub not_before: u64,
41 pub expires_at: u64,
42 pub withdrawn: bool,
43}
44
45impl RelationScopedLocator {
46 pub fn validate_locator_use(
53 &self,
54 requested_purpose: u64,
55 current_epoch: u64,
56 is_proxy_hop: bool,
57 ) -> Result<(), QdnfError> {
58 if self.locator_hash == 0
59 || self.direction_hash == 0
60 || self.relation_context_hash == 0
61 || self.purpose_bind_hash == 0
62 {
63 return Err(QdnfError::Malformed);
64 }
65 if self.withdrawn
66 || self.not_before >= self.expires_at
67 || current_epoch < self.not_before
68 || current_epoch >= self.expires_at
69 {
70 return Err(QdnfError::Expired);
71 }
72 let _ = is_proxy_hop;
74 if requested_purpose == 0 || requested_purpose != self.purpose_bind_hash {
75 return Err(QdnfError::Denied);
76 }
77 Ok(())
78 }
79
80 #[inline]
84 pub const fn merge_counterparts(&self, _reverse: &Self) -> Result<(), QdnfError> {
85 Err(QdnfError::Unauthorized)
86 }
87
88 #[inline]
91 pub const fn admit_public_qsr_publication(&self) -> Result<(), QdnfError> {
92 if self.withdrawn {
93 return Err(QdnfError::Expired);
94 }
95 if self.audience_scope.can_publish_to_public_qsr() {
96 Ok(())
97 } else {
98 Err(QdnfError::Denied)
99 }
100 }
101}
102
103#[inline]
105pub fn validate_locator_use(
106 locator: &RelationScopedLocator,
107 requested_purpose: u64,
108 current_epoch: u64,
109 is_proxy_hop: bool,
110) -> Result<(), QdnfError> {
111 locator.validate_locator_use(requested_purpose, current_epoch, is_proxy_hop)
112}
113
114#[cfg(test)]
115mod tests {
116 use super::*;
117 use crate::q_hash;
118
119 fn sample_pair() -> (RelationScopedLocator, RelationScopedLocator) {
120 let ctx = q_hash("urn:qualia:rel:jane-bob-2026");
121 let purpose = q_hash("urn:qualia:purpose:clinical-consult");
122 let jane_to_bob = RelationScopedLocator {
123 locator_hash: q_hash("mailto:jane@bob.example"),
124 direction_hash: q_hash("dir:jane->bob"),
125 relation_context_hash: ctx,
126 purpose_bind_hash: purpose,
127 audience_scope: AudienceScope::PrivatePairwise,
128 not_before: 1_000,
129 expires_at: 2_000,
130 withdrawn: false,
131 };
132 let bob_to_jane = RelationScopedLocator {
133 locator_hash: q_hash("mailto:bob@jane.example"),
134 direction_hash: q_hash("dir:bob->jane"),
135 relation_context_hash: ctx,
136 purpose_bind_hash: purpose,
137 audience_scope: AudienceScope::PrivatePairwise,
138 not_before: 1_000,
139 expires_at: 2_000,
140 withdrawn: false,
141 };
142 (jane_to_bob, bob_to_jane)
143 }
144
145 #[test]
146 fn directed_mailboxes_are_distinct_and_never_merge_counterparts() {
147 let (a_to_b, b_to_a) = sample_pair();
148 assert_ne!(a_to_b.locator_hash, b_to_a.locator_hash);
149 assert_ne!(a_to_b.direction_hash, b_to_a.direction_hash);
150 assert_eq!(
151 a_to_b.merge_counterparts(&b_to_a),
152 Err(QdnfError::Unauthorized)
153 );
154 }
155
156 #[test]
157 fn expired_or_withdrawn_locator_fails_closed() {
158 let (mut loc, _) = sample_pair();
159 let purpose = loc.purpose_bind_hash;
160 assert_eq!(validate_locator_use(&loc, purpose, 1_500, false), Ok(()));
161 assert_eq!(
162 validate_locator_use(&loc, purpose, 999, false),
163 Err(QdnfError::Expired)
164 );
165 assert_eq!(
166 validate_locator_use(&loc, purpose, 2_000, false),
167 Err(QdnfError::Expired)
168 );
169 loc.withdrawn = true;
170 assert_eq!(
171 validate_locator_use(&loc, purpose, 1_500, false),
172 Err(QdnfError::Expired)
173 );
174 }
175
176 #[test]
177 fn proxy_hop_cannot_launder_purpose_mismatch() {
178 let (loc, _) = sample_pair();
179 let wrong_purpose = q_hash("urn:qualia:purpose:ad-targeting");
180 assert_eq!(
181 validate_locator_use(&loc, wrong_purpose, 1_500, false),
182 Err(QdnfError::Denied)
183 );
184 assert_eq!(
185 validate_locator_use(&loc, wrong_purpose, 1_500, true),
186 Err(QdnfError::Denied)
187 );
188 }
189
190 #[test]
191 fn private_pairwise_locator_refuses_public_qsr_publication() {
192 let (loc, _) = sample_pair();
193 assert_eq!(loc.admit_public_qsr_publication(), Err(QdnfError::Denied));
194 }
195}