Skip to main content

qualia_core_db/did_qi/
service.rs

1//! CSCP mailbox service entries (spec §10).
2//!
3//! Under relay-only disclosure, Direct locators and `publicDht` are forbidden.
4
5use super::QiError;
6
7pub const SERVICE_TYPE: &str = "CscpMailbox";
8pub const MAX_HINTS: usize = 8;
9pub const MAX_HINT_ID: usize = 64;
10
11#[repr(u8)]
12#[derive(Clone, Copy, Debug, PartialEq, Eq)]
13pub enum LocatorClass {
14    Mailbox = 1,
15    RelayHint = 2,
16    Direct = 3,
17}
18
19#[repr(u8)]
20#[derive(Clone, Copy, Debug, PartialEq, Eq)]
21pub enum Disclosure {
22    DirectPermitted = 1,
23    ApprovedRelaysOnly = 2,
24    QualifiedMultiHop = 3,
25    Isolated = 4,
26}
27
28impl Disclosure {
29    /// `true` when `relay_only`.
30    pub const fn is_relay_only(self) -> bool {
31        !matches!(self, Disclosure::DirectPermitted)
32    }
33
34    /// `Disclosure::json_name`.
35    pub const fn json_name(self) -> &'static [u8] {
36        match self {
37            Disclosure::DirectPermitted => b"DirectPermitted",
38            Disclosure::ApprovedRelaysOnly => b"ApprovedRelaysOnly",
39            Disclosure::QualifiedMultiHop => b"QualifiedMultiHop",
40            Disclosure::Isolated => b"Isolated",
41        }
42    }
43}
44
45impl LocatorClass {
46    /// JSON wire name.
47    pub const fn json_name(self) -> &'static [u8] {
48        match self {
49            LocatorClass::Mailbox => b"mailbox",
50            LocatorClass::RelayHint => b"relayHint",
51            LocatorClass::Direct => b"direct",
52        }
53    }
54}
55
56#[derive(Clone, Copy, Debug, PartialEq, Eq)]
57pub struct RelayHint {
58    pub hint_id: [u8; MAX_HINT_ID],
59    pub hint_id_len: u8,
60    pub operator_hash: [u8; 32],
61}
62
63impl RelayHint {
64    /// Creates a default `RelayHint`.
65    pub fn new(hint_id: &[u8], operator_hash: [u8; 32]) -> Result<Self, QiError> {
66        if hint_id.is_empty() || hint_id.len() > MAX_HINT_ID {
67            return Err(QiError::MalformedDocument);
68        }
69        let mut h = Self {
70            hint_id: [0u8; MAX_HINT_ID],
71            hint_id_len: hint_id.len() as u8,
72            operator_hash,
73        };
74        h.hint_id[..hint_id.len()].copy_from_slice(hint_id);
75        Ok(h)
76    }
77}
78
79#[derive(Clone, Copy, Debug, PartialEq, Eq)]
80pub struct CscpMailbox {
81    pub kind: LocatorClass,
82    pub disclosure: Disclosure,
83    pub contact_key: [u8; 32],
84    pub public_dht: bool,
85    pub generation: u32,
86    pub hint_count: u8,
87    pub hints: [RelayHint; MAX_HINTS],
88}
89
90impl CscpMailbox {
91    /// `CscpMailbox::mailbox`.
92    pub const fn mailbox(contact_key: [u8; 32], disclosure: Disclosure) -> Self {
93        Self {
94            kind: LocatorClass::Mailbox,
95            disclosure,
96            contact_key,
97            public_dht: false,
98            generation: 0,
99            hint_count: 0,
100            hints: [RelayHint {
101                hint_id: [0u8; MAX_HINT_ID],
102                hint_id_len: 0,
103                operator_hash: [0u8; 32],
104            }; MAX_HINTS],
105        }
106    }
107
108    /// `CscpMailbox::direct`.
109    pub const fn direct(contact_key: [u8; 32], disclosure: Disclosure) -> Self {
110        let mut s = Self::mailbox(contact_key, disclosure);
111        s.kind = LocatorClass::Direct;
112        s
113    }
114
115    /// `true` when `direct`.
116    pub const fn is_direct(&self) -> bool {
117        matches!(self.kind, LocatorClass::Direct)
118    }
119}
120
121/// Spec §10.3: relay-only documents MUST NOT carry Direct locators or public DHT.
122pub fn check_relay_only(services: &[CscpMailbox]) -> Result<(), QiError> {
123    let mut relay_only = false;
124    let mut i = 0;
125    while i < services.len() {
126        if services[i].disclosure.is_relay_only() {
127            relay_only = true;
128        }
129        i += 1;
130    }
131    if !relay_only {
132        return Ok(());
133    }
134    i = 0;
135    while i < services.len() {
136        if services[i].is_direct() || services[i].public_dht {
137            return Err(QiError::DirectLocatorForbidden);
138        }
139        i += 1;
140    }
141    Ok(())
142}
143
144#[cfg(test)]
145mod tests {
146    use super::*;
147
148    #[test]
149    fn relay_only_document_with_direct_locator_rejected() {
150        let services = [CscpMailbox::direct(
151            [9u8; 32],
152            Disclosure::ApprovedRelaysOnly,
153        )];
154        assert_eq!(
155            check_relay_only(&services),
156            Err(QiError::DirectLocatorForbidden)
157        );
158        let mailbox = [CscpMailbox::mailbox(
159            [9u8; 32],
160            Disclosure::ApprovedRelaysOnly,
161        )];
162        assert_eq!(check_relay_only(&mailbox), Ok(()));
163        let permitted_direct = [CscpMailbox::direct([9u8; 32], Disclosure::DirectPermitted)];
164        assert_eq!(check_relay_only(&permitted_direct), Ok(()));
165    }
166
167    #[test]
168    fn service_type_is_cscp_mailbox() {
169        assert_eq!(SERVICE_TYPE, "CscpMailbox");
170        assert_eq!(LocatorClass::Direct.json_name(), b"direct");
171        assert_eq!(
172            Disclosure::ApprovedRelaysOnly.json_name(),
173            b"ApprovedRelaysOnly"
174        );
175    }
176}