Skip to main content

qualia_core_db/net/qdnf/fabric/
locator.rs

1//! F7 Relation-Scoped Locators (`NET-21`, `identifier-fabric-integration.md` §3).
2//!
3//! Pairwise directional addresses (such as `jane@bob.tld` <-> `bob@jane.tld`) and
4//! service-bond locators bind direction, relationship context, purpose, audience,
5//! and temporal lifecycle. Two directed mailboxes between the same counterparts
6//! are two distinct instruments and never merge the counterparts' `NaturalAgent`
7//! records. Proxy hops inherit purpose restrictions (`no-proxy-launder`, spine §3n).
8
9use crate::net::qdnf::errors::QdnfError;
10
11/// Publication and disclosure scope for a relation-scoped locator.
12#[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    /// Private alias-to-person bindings and full counterpart graphs are never
23    /// public `QSR` discovery records (`identifier-fabric-integration.md` §3).
24    #[inline]
25    pub const fn can_publish_to_public_qsr(self) -> bool {
26        matches!(self, Self::PublicService)
27    }
28}
29
30/// Zero-heap relation-scoped locator instrument (F2 `idf:RelationScopedLocatorShape`).
31#[repr(C)]
32#[derive(Clone, Copy, Debug, PartialEq, Eq)]
33pub struct RelationScopedLocator {
34    pub locator_hash: u64,
35    /// Directional hash (`A -> B` != `B -> A`).
36    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    /// Validate that this relation-scoped locator may be used for `requested_purpose`
47    /// at `current_epoch`.
48    ///
49    /// - Withdrawn or out-of-window locators fail closed with [`QdnfError::Expired`].
50    /// - Purpose mismatch fails closed with [`QdnfError::Denied`], even when
51    ///   `is_proxy_hop == true` (enforcing spine §3n **no-proxy-launder**).
52    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        // Spine §3n: a proxy hop cannot launder or strip the upstream purpose binding.
73        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    /// Two directed locators (`A -> B` and `B -> A`) between counterparts are two
81    /// distinct instruments. Attempting to merge counterparts or infer a single
82    /// `NaturalAgent` from pairwise locators always fails closed.
83    #[inline]
84    pub const fn merge_counterparts(&self, _reverse: &Self) -> Result<(), QdnfError> {
85        Err(QdnfError::Unauthorized)
86    }
87
88    /// Admit publication to a public QSR directory. Private pairwise and closed-group
89    /// locators are refused (`QdnfError::Denied`).
90    #[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/// Convenience free-function wrapper for [`RelationScopedLocator::validate_locator_use`].
104#[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}