Skip to main content

qualia_core_db/net/qdnf/bearer/
nym.rs

1//! Nym mixnet transition bearer framing and deterministic loopback carrier.
2//!
3//! Encapsulates QFrames into Sphinx-compatible datagram envelopes.
4//! Bounded, zero-heap in hot path. Labelled transition carrier (not Native Independent).
5//! Authoritative QdnfError variants mapped (Closed, NoRoute, WouldBlock, Capacity).
6
7use crate::net::qdnf::bearer::contract::{check_frame_mtu, Bearer, RecvMeta};
8use crate::net::qdnf::errors::QdnfError;
9use crate::net::qdnf::registries::BearerProfile;
10use crate::net::qdnf::types::{ObservedLocator, ScopeEpoch};
11
12/// 4-byte magic for Nym mixnet envelopes.
13pub const NYM_MAGIC: [u8; 4] = *b"QNYM";
14/// Current envelope protocol version.
15pub const NYM_ENVELOPE_VERSION: u8 = 1;
16/// Header length: magic(4) + version(1) + payload_len(2) + sender_len(1) + sender(32) = 40 bytes.
17pub const NYM_HEADER_LEN: usize = 40;
18/// Sphinx maximum payload size for standard Nym packets (1,024 bytes).
19pub const NYM_SPHINX_MTU: u16 = 1024;
20
21/// Encapsulate a QFrame into a Nym Sphinx payload envelope.
22///
23/// Output layout:
24/// `[0..4]`: `b"QNYM"`
25/// `[4]`: version `1`
26/// `[5..7]`: big-endian payload length
27/// `[7]`: sender locator byte length (0..=32)
28/// `[8..40]`: sender locator bytes
29/// `[40..40+payload_len]`: frame bytes
30pub fn encapsulate_nym(
31    sender: &ObservedLocator,
32    frame: &[u8],
33    out: &mut [u8],
34) -> Result<usize, QdnfError> {
35    let total_len = NYM_HEADER_LEN + frame.len();
36    if total_len > out.len() {
37        return Err(QdnfError::Capacity);
38    }
39    if frame.len() > u16::MAX as usize {
40        return Err(QdnfError::Range);
41    }
42
43    out[0..4].copy_from_slice(&NYM_MAGIC);
44    out[4] = NYM_ENVELOPE_VERSION;
45    let len_be = (frame.len() as u16).to_be_bytes();
46    out[5..7].copy_from_slice(&len_be);
47    out[7] = sender.len;
48    out[8..40].copy_from_slice(&sender.bytes);
49    out[40..total_len].copy_from_slice(frame);
50
51    Ok(total_len)
52}
53
54/// Decapsulate a Nym Sphinx payload envelope into a QFrame and sender locator.
55pub fn decapsulate_nym(
56    src: &[u8],
57    out_sender: &mut ObservedLocator,
58    out_frame: &mut [u8],
59) -> Result<usize, QdnfError> {
60    if src.len() < NYM_HEADER_LEN {
61        return Err(QdnfError::Truncated);
62    }
63    if src[0..4] != NYM_MAGIC {
64        return Err(QdnfError::Malformed);
65    }
66    if src[4] != NYM_ENVELOPE_VERSION {
67        return Err(QdnfError::Unsupported);
68    }
69
70    let frame_len = u16::from_be_bytes([src[5], src[6]]) as usize;
71    if src.len() < NYM_HEADER_LEN + frame_len {
72        return Err(QdnfError::Truncated);
73    }
74    if frame_len > out_frame.len() {
75        return Err(QdnfError::Capacity);
76    }
77
78    let sender_len = src[7];
79    if sender_len > 32 {
80        return Err(QdnfError::Malformed);
81    }
82    let mut sender_bytes = [0u8; 32];
83    sender_bytes.copy_from_slice(&src[8..40]);
84    *out_sender = ObservedLocator {
85        bytes: sender_bytes,
86        len: sender_len,
87    };
88
89    out_frame[..frame_len].copy_from_slice(&src[40..40 + frame_len]);
90    Ok(frame_len)
91}
92
93/// Deterministic, zero-heap in-memory simulated Nym mixnet bearer.
94/// Used for pure integration testing of the QSession handshake over Nym.
95pub struct NymSimulatedBearer {
96    local_locator: ObservedLocator,
97    peer_locator: ObservedLocator,
98    scope: ScopeEpoch,
99    closed: bool,
100    inbound_buf: [u8; NYM_SPHINX_MTU as usize],
101    inbound_len: usize,
102    inbound_src: ObservedLocator,
103}
104
105impl NymSimulatedBearer {
106    /// Creates a default `NymSimulatedBearer`.
107    pub fn new(local_locator: ObservedLocator, peer_locator: ObservedLocator) -> Self {
108        Self {
109            local_locator,
110            peer_locator,
111            scope: ScopeEpoch { scope: 1, epoch: 1 },
112            closed: false,
113            inbound_buf: [0u8; NYM_SPHINX_MTU as usize],
114            inbound_len: 0,
115            inbound_src: ObservedLocator::EMPTY,
116        }
117    }
118
119    #[inline]
120    /// `NymSimulatedBearer::local_locator`.
121    pub fn local_locator(&self) -> &ObservedLocator {
122        &self.local_locator
123    }
124
125    /// Simulate delivery of a Sphinx envelope into this bearer's receive buffer.
126    pub fn deliver_envelope(&mut self, envelope: &[u8]) -> Result<(), QdnfError> {
127        if self.closed {
128            return Err(QdnfError::Closed);
129        }
130        let mut sender = ObservedLocator::EMPTY;
131        let mut frame_out = [0u8; NYM_SPHINX_MTU as usize];
132        let n = decapsulate_nym(envelope, &mut sender, &mut frame_out)?;
133        self.inbound_buf[..n].copy_from_slice(&frame_out[..n]);
134        self.inbound_len = n;
135        self.inbound_src = sender;
136        Ok(())
137    }
138}
139
140impl Bearer for NymSimulatedBearer {
141    fn profile(&self) -> BearerProfile {
142        BearerProfile::NymMixnetTransitionV1
143    }
144
145    fn mtu(&self) -> u16 {
146        NYM_SPHINX_MTU
147    }
148
149    fn scope(&self) -> ScopeEpoch {
150        self.scope
151    }
152
153    fn send(&mut self, dest: &ObservedLocator, frame: &[u8]) -> Result<usize, QdnfError> {
154        if self.closed {
155            return Err(QdnfError::Closed);
156        }
157        check_frame_mtu(frame.len(), self.mtu())?;
158        if *dest != self.peer_locator && *dest != ObservedLocator::EMPTY {
159            return Err(QdnfError::NoRoute);
160        }
161        Ok(frame.len())
162    }
163
164    fn recv(&mut self, out: &mut [u8]) -> Result<(usize, RecvMeta), QdnfError> {
165        if self.closed {
166            return Err(QdnfError::Closed);
167        }
168        if self.inbound_len == 0 {
169            return Err(QdnfError::WouldBlock);
170        }
171        let len = self.inbound_len;
172        if out.len() < len {
173            return Err(QdnfError::Capacity);
174        }
175        out[..len].copy_from_slice(&self.inbound_buf[..len]);
176        let src = self.inbound_src;
177        self.inbound_len = 0;
178        self.inbound_src = ObservedLocator::EMPTY;
179
180        Ok((
181            len,
182            RecvMeta {
183                observed_source: src,
184                scope: self.scope,
185                mtu: NYM_SPHINX_MTU,
186            },
187        ))
188    }
189
190    fn shutdown(&mut self) -> Result<(), QdnfError> {
191        self.closed = true;
192        self.inbound_len = 0;
193        Ok(())
194    }
195}
196
197#[cfg(test)]
198mod tests {
199    use super::*;
200
201    #[test]
202    fn nym_envelope_roundtrips() {
203        let sender = ObservedLocator::from_slice(b"alice-client.sphinx@gateway-1").unwrap();
204        let payload = b"hello over nym mixnet";
205        let mut envelope = [0u8; 256];
206        let enc_len = encapsulate_nym(&sender, payload, &mut envelope).unwrap();
207
208        assert_eq!(&envelope[0..4], &NYM_MAGIC);
209        assert_eq!(envelope[4], NYM_ENVELOPE_VERSION);
210
211        let mut out_sender = ObservedLocator::EMPTY;
212        let mut out_frame = [0u8; 256];
213        let dec_len =
214            decapsulate_nym(&envelope[..enc_len], &mut out_sender, &mut out_frame).unwrap();
215
216        assert_eq!(dec_len, payload.len());
217        assert_eq!(&out_frame[..dec_len], payload);
218        assert_eq!(out_sender, sender);
219    }
220
221    #[test]
222    fn simulated_bearer_sends_and_receives() {
223        let alice_loc = ObservedLocator::from_slice(b"alice").unwrap();
224        let bob_loc = ObservedLocator::from_slice(b"bob").unwrap();
225        let mut bob_bearer = NymSimulatedBearer::new(bob_loc, alice_loc);
226
227        assert_eq!(bob_bearer.profile(), BearerProfile::NymMixnetTransitionV1);
228        assert!(!bob_bearer.profile().native_independent());
229        assert_eq!(bob_bearer.mtu(), NYM_SPHINX_MTU);
230
231        // Prepare an envelope from Alice to Bob
232        let payload = b"ConnectRequest(did:qi:alice)";
233        let mut envelope = [0u8; 512];
234        let enc_len = encapsulate_nym(&alice_loc, payload, &mut envelope).unwrap();
235
236        // Deliver envelope to Bob
237        bob_bearer.deliver_envelope(&envelope[..enc_len]).unwrap();
238
239        // Bob reads from bearer
240        let mut rx_buf = [0u8; 512];
241        let (n, meta) = bob_bearer.recv(&mut rx_buf).unwrap();
242        assert_eq!(n, payload.len());
243        assert_eq!(&rx_buf[..n], payload);
244        assert_eq!(meta.observed_source, alice_loc);
245    }
246}