Skip to main content

clm_rust_core/mesh/
reticulum_codec.rs

1//! Reticulum Announce Codec for CLM Layer 3 Mesh.
2//! Canonical Path: kernel/clm_rust_core/src/mesh/reticulum_codec.rs
3//!
4//! Provides zero-copy parsing and serialization of Reticulum Announce frames,
5//! Ed25519 signature verification, and MCard capability manifest unpacking.
6
7use ed25519_dalek::{Signature, Signer, SigningKey, Verifier, VerifyingKey};
8use serde::{Deserialize, Serialize};
9use thiserror::Error;
10
11#[derive(Error, Debug)]
12pub enum ReticulumCodecError {
13    #[error("Announce packet too short: expected at least {expected}, got {got}")]
14    BufferTooShort { expected: usize, got: usize },
15
16    #[error("Unsupported packet type: {0}")]
17    UnsupportedPacketType(u8),
18
19    #[error("Malformed app data length header or payload truncated")]
20    PayloadTruncated,
21
22    #[error("Invalid Ed25519 public key")]
23    InvalidPublicKey,
24
25    #[error("Invalid Ed25519 signature")]
26    InvalidSignature,
27
28    #[error("JSON deserialization error: {0}")]
29    JsonError(#[from] serde_json::Error),
30}
31
32/// Parsed Reticulum announce frame components
33#[derive(Debug, Clone, PartialEq, Eq)]
34pub struct ReticulumAnnounceData {
35    pub destination_hash: [u8; 16],
36    pub public_key: [u8; 32],
37    pub app_data: Vec<u8>,
38    pub signature: [u8; 64],
39}
40
41/// Structured PKC capability manifest within announce app-data
42#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
43pub struct PkcAnnouncePayload {
44    pub did: String,
45    #[serde(default)]
46    pub capabilities: Vec<String>,
47    #[serde(default)]
48    pub namespaces: Vec<String>,
49    #[serde(default)]
50    pub timestamp: f64,
51    #[serde(flatten)]
52    pub extra: serde_json::Map<String, serde_json::Value>,
53}
54
55/// Verified and decoded peer record
56#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
57pub struct DecodedPkcPeer {
58    pub destination_hex: String,
59    pub identity_public_key_hex: String,
60    pub payload: PkcAnnouncePayload,
61    pub verified: bool,
62}
63
64/// Encodes an announce packet into a canonical binary frame.
65/// Framing: [0x01 (1B)][dest (16B)][pubkey (32B)][appData_len (2B BE)][appData (NB)][sig (64B)]
66pub fn encode_announce_packet(data: &ReticulumAnnounceData) -> Vec<u8> {
67    let mut buf = Vec::with_capacity(1 + 16 + 32 + 2 + data.app_data.len() + 64);
68    buf.push(0x01); // Announce packet type
69    buf.extend_from_slice(&data.destination_hash);
70    buf.extend_from_slice(&data.public_key);
71    let app_data_len = data.app_data.len() as u16;
72    buf.extend_from_slice(&app_data_len.to_be_bytes());
73    buf.extend_from_slice(&data.app_data);
74    buf.extend_from_slice(&data.signature);
75    buf
76}
77
78/// Decodes a binary frame into Reticulum announce components.
79pub fn decode_announce_packet(buffer: &[u8]) -> Result<ReticulumAnnounceData, ReticulumCodecError> {
80    const MIN_LEN: usize = 1 + 16 + 32 + 2 + 64; // 115 bytes
81    if buffer.len() < MIN_LEN {
82        return Err(ReticulumCodecError::BufferTooShort {
83            expected: MIN_LEN,
84            got: buffer.len(),
85        });
86    }
87
88    if buffer[0] != 0x01 {
89        return Err(ReticulumCodecError::UnsupportedPacketType(buffer[0]));
90    }
91
92    let mut offset = 1;
93    let mut destination_hash = [0u8; 16];
94    destination_hash.copy_from_slice(&buffer[offset..offset + 16]);
95    offset += 16;
96
97    let mut public_key = [0u8; 32];
98    public_key.copy_from_slice(&buffer[offset..offset + 32]);
99    offset += 32;
100
101    let app_data_len = u16::from_be_bytes([buffer[offset], buffer[offset + 1]]) as usize;
102    offset += 2;
103
104    if buffer.len() < offset + app_data_len + 64 {
105        return Err(ReticulumCodecError::PayloadTruncated);
106    }
107
108    let app_data = buffer[offset..offset + app_data_len].to_vec();
109    offset += app_data_len;
110
111    let mut signature = [0u8; 64];
112    signature.copy_from_slice(&buffer[offset..offset + 64]);
113
114    Ok(ReticulumAnnounceData {
115        destination_hash,
116        public_key,
117        app_data,
118        signature,
119    })
120}
121
122/// Signs announce components using an Ed25519 signing key.
123/// Signed payload = destination_hash + public_key + app_data
124pub fn sign_announce_data(
125    destination_hash: &[u8; 16],
126    public_key: &[u8; 32],
127    app_data: &[u8],
128    signing_key: &SigningKey,
129) -> [u8; 64] {
130    let mut payload = Vec::with_capacity(16 + 32 + app_data.len());
131    payload.extend_from_slice(destination_hash);
132    payload.extend_from_slice(public_key);
133    payload.extend_from_slice(app_data);
134
135    let signature = signing_key.sign(&payload);
136    signature.to_bytes()
137}
138
139/// Verifies Ed25519 signature over destination_hash + public_key + app_data.
140pub fn verify_announce_signature(data: &ReticulumAnnounceData) -> bool {
141    let verifying_key = match VerifyingKey::from_bytes(&data.public_key) {
142        Ok(k) => k,
143        Err(_) => return false,
144    };
145
146    let signature = match Signature::from_slice(&data.signature) {
147        Ok(s) => s,
148        Err(_) => return false,
149    };
150
151    let mut payload = Vec::with_capacity(16 + 32 + data.app_data.len());
152    payload.extend_from_slice(&data.destination_hash);
153    payload.extend_from_slice(&data.public_key);
154    payload.extend_from_slice(&data.app_data);
155
156    verifying_key.verify(&payload, &signature).is_ok()
157}
158
159/// Parses and verifies an announce frame into a DecodedPkcPeer.
160pub fn parse_and_verify_peer(buffer: &[u8]) -> Result<DecodedPkcPeer, ReticulumCodecError> {
161    let announce = decode_announce_packet(buffer)?;
162    let verified = verify_announce_signature(&announce);
163    if !verified {
164        return Err(ReticulumCodecError::InvalidSignature);
165    }
166
167    let payload: PkcAnnouncePayload = serde_json::from_slice(&announce.app_data)?;
168
169    Ok(DecodedPkcPeer {
170        destination_hex: hex::encode(announce.destination_hash),
171        identity_public_key_hex: hex::encode(announce.public_key),
172        payload,
173        verified,
174    })
175}
176
177#[cfg(test)]
178mod tests {
179    use super::*;
180    use rand::rngs::OsRng;
181
182    #[test]
183    fn test_codec_roundtrip_and_signature_verification() {
184        let mut csprng = OsRng;
185        let signing_key = SigningKey::generate(&mut csprng);
186        let verifying_key = signing_key.verifying_key();
187        let pub_bytes = verifying_key.to_bytes();
188
189        let dest_hash = [0x42u8; 16];
190        let app_payload = PkcAnnouncePayload {
191            did: "did:clm:peer1".into(),
192            capabilities: vec!["mcard:text".into(), "satori:dialogue".into()],
193            namespaces: vec!["clm:pkc/local".into()],
194            timestamp: 1726500000.0,
195            extra: serde_json::Map::new(),
196        };
197        let app_data = serde_json::to_vec(&app_payload).unwrap();
198
199        let sig = sign_announce_data(&dest_hash, &pub_bytes, &app_data, &signing_key);
200
201        let announce = ReticulumAnnounceData {
202            destination_hash: dest_hash,
203            public_key: pub_bytes,
204            app_data: app_data.clone(),
205            signature: sig,
206        };
207
208        let encoded = encode_announce_packet(&announce);
209        assert_eq!(encoded[0], 0x01);
210
211        let decoded = decode_announce_packet(&encoded).unwrap();
212        assert_eq!(decoded.destination_hash, dest_hash);
213        assert_eq!(decoded.public_key, pub_bytes);
214        assert_eq!(decoded.app_data, app_data);
215        assert_eq!(decoded.signature, sig);
216
217        assert!(verify_announce_signature(&decoded));
218
219        // Tamper test
220        let mut tampered = encoded.clone();
221        tampered[51] ^= 0xff; // Alter byte inside app_data
222        let tampered_decoded = decode_announce_packet(&tampered).unwrap();
223        assert!(!verify_announce_signature(&tampered_decoded));
224    }
225}