Skip to main content

nexer_protocol/
lib.rs

1//! Nexer Tunnel Protocol primitives.
2//!
3//! This crate intentionally owns only the shared wire contract: JSON envelope
4//! parsing, strict protocol-token validation, frame encoding/decoding, target
5//! policy helpers, and canonical data-connection signature input. Client CLI,
6//! socket orchestration, gateway state, auth backends, and product policy belong
7//! in `nexer` and `nexerd`.
8
9#![forbid(unsafe_code)]
10
11use base64::Engine as _;
12use ring::hmac;
13use serde::de::{Error as DeError, MapAccess, Visitor};
14use serde::{Deserialize, Deserializer, Serialize, Serializer};
15use serde_json::value::RawValue;
16use std::collections::{BTreeMap, BTreeSet};
17use std::fmt;
18use std::num::NonZeroU16;
19use std::str::FromStr;
20use thiserror::Error;
21use zeroize::Zeroize;
22
23pub const PROTOCOL_VERSION: u16 = 1;
24pub const MAX_FRAME_BYTES: usize = 64 * 1024;
25
26pub mod message_type {
27    pub const HELLO: &str = "hello";
28    pub const WELCOME: &str = "welcome";
29    pub const REGISTER_SERVICES: &str = "register_services";
30    pub const REGISTER_SERVICES_RESULT: &str = "register_services_result";
31    pub const EXPOSE_PORT: &str = "expose_port";
32    pub const EXPOSE_PORT_RESULT: &str = "expose_port_result";
33    pub const PREPARE_SERVICE: &str = "prepare_service";
34    pub const PREPARE_SERVICE_RESULT: &str = "prepare_service_result";
35    pub const UNREGISTER_SERVICES: &str = "unregister_services";
36    pub const UNREGISTER_SERVICES_RESULT: &str = "unregister_services_result";
37    pub const CONNECT_STREAM: &str = "connect_stream";
38    pub const CONNECT_STREAM_RESULT: &str = "connect_stream_result";
39    pub const OPEN_STREAM: &str = "open_stream";
40    pub const OPEN_STREAM_RESULT: &str = "open_stream_result";
41    pub const DATA_HELLO: &str = "data_hello";
42    pub const DATA_READY: &str = "data_ready";
43    pub const SERVICE_STATUS: &str = "service_status";
44    pub const PING: &str = "ping";
45    pub const PONG: &str = "pong";
46    pub const STREAM_CLOSED: &str = "stream_closed";
47    pub const ERROR: &str = "error";
48}
49
50pub mod service_protocol {
51    /// Generic opaque TCP service.
52    ///
53    /// Application protocols such as database or cache names are intentionally
54    /// not constants in this crate. `Service::protocol` is an open token owned
55    /// by product/tool layers, not a closed enum in the wire contract.
56    pub const TCP: &str = "tcp";
57}
58
59pub mod service_status {
60    pub const READY: &str = "ready";
61    pub const UNREACHABLE: &str = "unreachable";
62    pub const DEGRADED: &str = "degraded";
63    pub const REMOVED: &str = "removed";
64}
65
66pub mod open_stream_status {
67    pub const CONNECTING: &str = "connecting";
68    pub const REJECTED: &str = "rejected";
69}
70
71pub mod expose_port_status {
72    pub const ACCEPTED: &str = "accepted";
73    pub const REJECTED: &str = "rejected";
74}
75
76pub mod connect_stream_status {
77    pub const CONNECTED: &str = "connected";
78    pub const REJECTED: &str = "rejected";
79}
80
81pub mod prepare_service_status {
82    pub const READY: &str = "ready";
83    pub const FAILED: &str = "failed";
84    pub const REJECTED: &str = "rejected";
85}
86
87pub mod error_code {
88    pub const BAD_FRAME: &str = "bad_frame";
89    pub const UNSUPPORTED_VERSION: &str = "unsupported_version";
90    pub const UNKNOWN_MESSAGE_TYPE: &str = "unknown_message_type";
91    pub const AUTH_FAILED: &str = "auth_failed";
92    pub const SHARE_NOT_AUTHORIZED: &str = "share_not_authorized";
93    pub const SERVICE_NOT_ALLOWED: &str = "service_not_allowed";
94    pub const TARGET_NOT_ALLOWED: &str = "target_not_allowed";
95    pub const UNKNOWN_SERVICE: &str = "unknown_service";
96    pub const UNKNOWN_STREAM: &str = "unknown_stream";
97    pub const STREAM_TIMEOUT: &str = "stream_timeout";
98    pub const SIGNATURE_INVALID: &str = "signature_invalid";
99    pub const NONCE_REUSED: &str = "nonce_reused";
100    pub const CAPACITY_EXCEEDED: &str = "capacity_exceeded";
101    pub const LOCAL_CONNECT_FAILED: &str = "local_connect_failed";
102    pub const BUFFER_LIMIT_EXCEEDED: &str = "buffer_limit_exceeded";
103    pub const PREPARE_FAILED: &str = "prepare_failed";
104}
105
106#[derive(Debug, Error)]
107pub enum ProtocolError {
108    #[error("JSON parse error: {0}")]
109    Json(#[from] serde_json::Error),
110    #[error("unsupported protocol version: {version}")]
111    UnsupportedVersion { version: u16 },
112    #[error("unknown message type: {0}")]
113    UnknownMessageType(Token),
114    #[error("invalid token in {field}: {reason}")]
115    InvalidToken {
116        field: &'static str,
117        reason: &'static str,
118    },
119    #[error("invalid field {field}: {message}")]
120    InvalidField {
121        field: &'static str,
122        message: String,
123    },
124    #[error("frame needs more bytes")]
125    NeedMore,
126    #[error("frame too large: {len} > {max}")]
127    FrameTooLarge { len: usize, max: usize },
128}
129
130impl ProtocolError {
131    pub fn code(&self) -> &'static str {
132        match self {
133            Self::UnsupportedVersion { .. } => error_code::UNSUPPORTED_VERSION,
134            Self::UnknownMessageType(_) => error_code::UNKNOWN_MESSAGE_TYPE,
135            _ => error_code::BAD_FRAME,
136        }
137    }
138}
139
140pub type Result<T> = std::result::Result<T, ProtocolError>;
141
142#[derive(Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
143pub struct Token(String);
144
145impl Token {
146    pub const MAX_LEN: usize = 256;
147
148    pub fn new(value: impl Into<String>) -> Result<Self> {
149        let value = value.into();
150        validate_token("token", &value)?;
151        Ok(Self(value))
152    }
153
154    pub fn as_str(&self) -> &str {
155        &self.0
156    }
157}
158
159impl fmt::Debug for Token {
160    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
161        f.debug_tuple("Token").field(&self.0).finish()
162    }
163}
164
165impl fmt::Display for Token {
166    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
167        f.write_str(&self.0)
168    }
169}
170
171impl FromStr for Token {
172    type Err = ProtocolError;
173
174    fn from_str(value: &str) -> Result<Self> {
175        Self::new(value)
176    }
177}
178
179impl TryFrom<String> for Token {
180    type Error = ProtocolError;
181
182    fn try_from(value: String) -> Result<Self> {
183        Self::new(value)
184    }
185}
186
187impl Serialize for Token {
188    fn serialize<S>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error>
189    where
190        S: Serializer,
191    {
192        serializer.serialize_str(&self.0)
193    }
194}
195
196impl<'de> Deserialize<'de> for Token {
197    fn deserialize<D>(deserializer: D) -> std::result::Result<Self, D::Error>
198    where
199        D: Deserializer<'de>,
200    {
201        let value = String::deserialize(deserializer)?;
202        Token::new(value).map_err(D::Error::custom)
203    }
204}
205
206#[derive(Clone, Debug, PartialEq, Eq)]
207pub struct Signature(String);
208
209impl Signature {
210    pub const HEX_SHA256_LEN: usize = 64;
211    pub const BASE64URL_SHA256_LEN: usize = 43;
212
213    pub fn new(value: impl Into<String>) -> Result<Self> {
214        let value = value.into();
215        validate_signature(&value)?;
216        Ok(Self(value))
217    }
218
219    pub fn as_str(&self) -> &str {
220        &self.0
221    }
222}
223
224impl fmt::Display for Signature {
225    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
226        f.write_str(&self.0)
227    }
228}
229
230impl FromStr for Signature {
231    type Err = ProtocolError;
232
233    fn from_str(value: &str) -> Result<Self> {
234        Self::new(value)
235    }
236}
237
238impl TryFrom<String> for Signature {
239    type Error = ProtocolError;
240
241    fn try_from(value: String) -> Result<Self> {
242        Self::new(value)
243    }
244}
245
246impl Serialize for Signature {
247    fn serialize<S>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error>
248    where
249        S: Serializer,
250    {
251        serializer.serialize_str(&self.0)
252    }
253}
254
255impl<'de> Deserialize<'de> for Signature {
256    fn deserialize<D>(deserializer: D) -> std::result::Result<Self, D::Error>
257    where
258        D: Deserializer<'de>,
259    {
260        let value = String::deserialize(deserializer)?;
261        Signature::new(value).map_err(D::Error::custom)
262    }
263}
264
265#[derive(Clone, PartialEq, Eq, Zeroize)]
266#[zeroize(drop)]
267pub struct Secret(String);
268
269impl Secret {
270    pub const MAX_LEN: usize = 4096;
271
272    pub fn new(value: impl Into<String>) -> Result<Self> {
273        let value = value.into();
274        validate_bounded_string("secret", &value, Self::MAX_LEN, false)?;
275        Ok(Self(value))
276    }
277
278    pub fn as_str(&self) -> &str {
279        &self.0
280    }
281}
282
283impl fmt::Debug for Secret {
284    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
285        f.write_str("Secret([redacted])")
286    }
287}
288
289impl Serialize for Secret {
290    fn serialize<S>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error>
291    where
292        S: Serializer,
293    {
294        serializer.serialize_str(&self.0)
295    }
296}
297
298impl<'de> Deserialize<'de> for Secret {
299    fn deserialize<D>(deserializer: D) -> std::result::Result<Self, D::Error>
300    where
301        D: Deserializer<'de>,
302    {
303        let value = String::deserialize(deserializer)?;
304        Secret::new(value).map_err(D::Error::custom)
305    }
306}
307
308#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
309pub struct Text(String);
310
311impl Text {
312    pub const MAX_LEN: usize = 4096;
313
314    pub fn new(value: impl Into<String>) -> Result<Self> {
315        let value = value.into();
316        validate_bounded_string("text", &value, Self::MAX_LEN, false)?;
317        Ok(Self(value))
318    }
319
320    pub fn as_str(&self) -> &str {
321        &self.0
322    }
323}
324
325impl FromStr for Text {
326    type Err = ProtocolError;
327
328    fn from_str(value: &str) -> Result<Self> {
329        Self::new(value)
330    }
331}
332
333impl<'de> Deserialize<'de> for Text {
334    fn deserialize<D>(deserializer: D) -> std::result::Result<Self, D::Error>
335    where
336        D: Deserializer<'de>,
337    {
338        let value = String::deserialize(deserializer)?;
339        Text::new(value).map_err(D::Error::custom)
340    }
341}
342
343#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize)]
344pub struct StringMap(BTreeMap<Token, Text>);
345
346impl StringMap {
347    pub fn new() -> Self {
348        Self::default()
349    }
350
351    pub fn insert(&mut self, key: Token, value: Text) -> Option<Text> {
352        self.0.insert(key, value)
353    }
354
355    pub fn get(&self, key: &Token) -> Option<&Text> {
356        self.0.get(key)
357    }
358
359    pub fn is_empty(&self) -> bool {
360        self.0.is_empty()
361    }
362
363    pub fn iter(&self) -> impl Iterator<Item = (&Token, &Text)> {
364        self.0.iter()
365    }
366}
367
368impl<'de> Deserialize<'de> for StringMap {
369    fn deserialize<D>(deserializer: D) -> std::result::Result<Self, D::Error>
370    where
371        D: Deserializer<'de>,
372    {
373        struct MapVisitor;
374
375        impl<'de> Visitor<'de> for MapVisitor {
376            type Value = StringMap;
377
378            fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
379                formatter.write_str("a map of protocol-token keys to text values")
380            }
381
382            fn visit_map<A>(self, mut access: A) -> std::result::Result<Self::Value, A::Error>
383            where
384                A: MapAccess<'de>,
385            {
386                let mut map = BTreeMap::new();
387                while let Some((key, value)) = access.next_entry::<Token, Text>()? {
388                    if map.insert(key.clone(), value).is_some() {
389                        return Err(A::Error::custom(format!("duplicate map key: {key}")));
390                    }
391                }
392                Ok(StringMap(map))
393            }
394        }
395
396        deserializer.deserialize_map(MapVisitor)
397    }
398}
399
400pub type Extensions = StringMap;
401pub type Metadata = StringMap;
402
403#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
404#[serde(deny_unknown_fields)]
405pub struct Agent {
406    pub name: Token,
407    #[serde(default, skip_serializing_if = "Option::is_none")]
408    pub version: Option<Token>,
409    #[serde(default, skip_serializing_if = "Option::is_none")]
410    pub platform: Option<Token>,
411}
412
413#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
414#[serde(deny_unknown_fields)]
415pub struct Auth {
416    pub method: Token,
417    pub api_key: Secret,
418}
419
420#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
421#[serde(deny_unknown_fields)]
422pub struct Account {
423    pub account_id: Token,
424    pub plan: Token,
425}
426
427#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
428#[serde(deny_unknown_fields)]
429pub struct Target {
430    pub host: Text,
431    pub port: NonZeroU16,
432}
433
434#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
435#[serde(deny_unknown_fields)]
436pub struct Service {
437    pub service_id: Token,
438    pub name: Text,
439    pub protocol: Token,
440    pub target: Target,
441    #[serde(default, skip_serializing_if = "StringMap::is_empty")]
442    pub metadata: Metadata,
443    #[serde(default, skip_serializing_if = "StringMap::is_empty")]
444    pub extensions: Extensions,
445}
446
447#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
448#[serde(deny_unknown_fields)]
449pub struct ErrorDetail {
450    pub code: Token,
451    pub message: Text,
452}
453
454#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
455#[serde(deny_unknown_fields)]
456pub struct AcceptedService {
457    pub service_id: Token,
458    pub route_id: Token,
459}
460
461#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
462#[serde(deny_unknown_fields)]
463pub struct RejectedService {
464    pub service_id: Token,
465    pub error: ErrorDetail,
466}
467
468#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
469#[serde(deny_unknown_fields)]
470pub struct Hello {
471    pub client_id: Token,
472    pub agent: Agent,
473    pub auth: Auth,
474    #[serde(default, skip_serializing_if = "Option::is_none")]
475    pub resume_session_id: Option<Token>,
476    #[serde(default, skip_serializing_if = "Vec::is_empty")]
477    pub features: Vec<Token>,
478    #[serde(default, skip_serializing_if = "Vec::is_empty")]
479    pub requested_entitlements: Vec<Token>,
480    #[serde(default, skip_serializing_if = "StringMap::is_empty")]
481    pub extensions: Extensions,
482}
483
484#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
485#[serde(deny_unknown_fields)]
486pub struct Welcome {
487    pub session_id: Token,
488    pub session_secret: Secret,
489    pub account: Account,
490    #[serde(default, skip_serializing_if = "Vec::is_empty")]
491    pub entitlements: Vec<Token>,
492    pub heartbeat_interval_ms: u32,
493    pub data_connect_timeout_ms: u32,
494    pub max_concurrent_streams: u32,
495    #[serde(default, skip_serializing_if = "Option::is_none")]
496    pub server_time: Option<Text>,
497    #[serde(default, skip_serializing_if = "StringMap::is_empty")]
498    pub extensions: Extensions,
499}
500
501#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
502#[serde(deny_unknown_fields)]
503pub struct RegisterServices {
504    pub share_id: Token,
505    pub services: Vec<Service>,
506    #[serde(default, skip_serializing_if = "StringMap::is_empty")]
507    pub extensions: Extensions,
508}
509
510#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
511#[serde(deny_unknown_fields)]
512pub struct RegisterServicesResult {
513    #[serde(default, skip_serializing_if = "Vec::is_empty")]
514    pub accepted: Vec<AcceptedService>,
515    #[serde(default, skip_serializing_if = "Vec::is_empty")]
516    pub rejected: Vec<RejectedService>,
517    #[serde(default, skip_serializing_if = "StringMap::is_empty")]
518    pub extensions: Extensions,
519}
520
521#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
522#[serde(deny_unknown_fields)]
523pub struct ExposePort {
524    pub share_id: Token,
525    pub service_id: Token,
526    pub name: Text,
527    pub protocol: Token,
528    pub target: Target,
529    pub reason: Token,
530    pub requested_by: Token,
531    #[serde(default, skip_serializing_if = "StringMap::is_empty")]
532    pub metadata: Metadata,
533    #[serde(default, skip_serializing_if = "StringMap::is_empty")]
534    pub extensions: Extensions,
535}
536
537#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
538#[serde(deny_unknown_fields)]
539pub struct ExposePortResult {
540    pub status: Token,
541    pub service_id: Token,
542    #[serde(default, skip_serializing_if = "Option::is_none")]
543    pub error: Option<ErrorDetail>,
544    #[serde(default, skip_serializing_if = "StringMap::is_empty")]
545    pub extensions: Extensions,
546}
547
548#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
549#[serde(deny_unknown_fields)]
550pub struct PrepareService {
551    /// Local service/action id configured on the client.
552    ///
553    /// The gateway may request this action, but the client decides whether the
554    /// id is known and allowed. The request never carries an executable command.
555    pub service_id: Token,
556    pub reason: Token,
557    pub requested_by: Token,
558    pub timeout_ms: u32,
559    #[serde(default, skip_serializing_if = "StringMap::is_empty")]
560    pub metadata: Metadata,
561    #[serde(default, skip_serializing_if = "StringMap::is_empty")]
562    pub extensions: Extensions,
563}
564
565#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
566#[serde(deny_unknown_fields)]
567pub struct PrepareServiceResult {
568    pub service_id: Token,
569    pub status: Token,
570    pub elapsed_ms: u64,
571    #[serde(default, skip_serializing_if = "Option::is_none")]
572    pub error: Option<ErrorDetail>,
573    #[serde(default, skip_serializing_if = "StringMap::is_empty")]
574    pub extensions: Extensions,
575}
576
577#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
578#[serde(deny_unknown_fields)]
579pub struct UnregisterServices {
580    pub share_id: Token,
581    pub service_ids: Vec<Token>,
582    #[serde(default, skip_serializing_if = "StringMap::is_empty")]
583    pub extensions: Extensions,
584}
585
586#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
587#[serde(deny_unknown_fields)]
588pub struct UnregisterServicesResult {
589    #[serde(default, skip_serializing_if = "Vec::is_empty")]
590    pub removed: Vec<Token>,
591    #[serde(default, skip_serializing_if = "Vec::is_empty")]
592    pub not_found: Vec<Token>,
593    #[serde(default, skip_serializing_if = "StringMap::is_empty")]
594    pub extensions: Extensions,
595}
596
597#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
598#[serde(deny_unknown_fields)]
599pub struct ConnectStream {
600    /// Diagnostic identity for the app-side proxy opening this native stream.
601    ///
602    /// Authorization is carried by `auth`; gateways must not authorize solely
603    /// from this client-provided identifier.
604    pub client_id: Token,
605    pub auth: Auth,
606    pub share_id: Token,
607    pub service_id: Token,
608    pub reason: Token,
609    pub connect_timeout_ms: u32,
610    #[serde(default, skip_serializing_if = "StringMap::is_empty")]
611    pub metadata: Metadata,
612    #[serde(default, skip_serializing_if = "StringMap::is_empty")]
613    pub extensions: Extensions,
614}
615
616#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
617#[serde(deny_unknown_fields)]
618pub struct ConnectStreamResult {
619    pub stream_id: Token,
620    pub status: Token,
621    #[serde(default, skip_serializing_if = "Option::is_none")]
622    pub error: Option<ErrorDetail>,
623    #[serde(default, skip_serializing_if = "StringMap::is_empty")]
624    pub extensions: Extensions,
625}
626
627#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
628#[serde(deny_unknown_fields)]
629pub struct OpenStream {
630    pub share_id: Token,
631    pub stream_id: Token,
632    pub service_id: Token,
633    pub reason: Token,
634    pub connect_timeout_ms: u32,
635    pub nonce: Token,
636    #[serde(default, skip_serializing_if = "StringMap::is_empty")]
637    pub extensions: Extensions,
638}
639
640#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
641#[serde(deny_unknown_fields)]
642pub struct OpenStreamResult {
643    pub stream_id: Token,
644    pub status: Token,
645    #[serde(default, skip_serializing_if = "Option::is_none")]
646    pub error: Option<ErrorDetail>,
647    #[serde(default, skip_serializing_if = "StringMap::is_empty")]
648    pub extensions: Extensions,
649}
650
651#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
652#[serde(deny_unknown_fields)]
653pub struct DataHello {
654    pub client_id: Token,
655    pub session_id: Token,
656    pub share_id: Token,
657    pub stream_id: Token,
658    pub service_id: Token,
659    pub nonce: Token,
660    pub signature: Signature,
661    #[serde(default, skip_serializing_if = "StringMap::is_empty")]
662    pub extensions: Extensions,
663}
664
665#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
666#[serde(deny_unknown_fields)]
667pub struct DataReady {
668    pub stream_id: Token,
669    #[serde(default, skip_serializing_if = "StringMap::is_empty")]
670    pub extensions: Extensions,
671}
672
673#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
674#[serde(deny_unknown_fields)]
675pub struct ServiceStatus {
676    pub share_id: Token,
677    pub service_id: Token,
678    pub status: Token,
679    #[serde(default, skip_serializing_if = "Option::is_none")]
680    pub error: Option<ErrorDetail>,
681    #[serde(default, skip_serializing_if = "StringMap::is_empty")]
682    pub extensions: Extensions,
683}
684
685#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
686#[serde(deny_unknown_fields)]
687pub struct Ping {
688    pub time: Text,
689    #[serde(default, skip_serializing_if = "StringMap::is_empty")]
690    pub extensions: Extensions,
691}
692
693#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
694#[serde(deny_unknown_fields)]
695pub struct Pong {
696    pub time: Text,
697    #[serde(default, skip_serializing_if = "StringMap::is_empty")]
698    pub extensions: Extensions,
699}
700
701#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
702#[serde(deny_unknown_fields)]
703pub struct StreamClosed {
704    pub share_id: Token,
705    pub service_id: Token,
706    pub stream_id: Token,
707    pub reason: Token,
708    pub bytes_in: u64,
709    pub bytes_out: u64,
710    #[serde(default, skip_serializing_if = "StringMap::is_empty")]
711    pub extensions: Extensions,
712}
713
714#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
715#[serde(deny_unknown_fields)]
716pub struct ErrorBody {
717    pub code: Token,
718    pub message: Text,
719    #[serde(default, skip_serializing_if = "StringMap::is_empty")]
720    pub extensions: Extensions,
721}
722
723#[derive(Clone, Debug, PartialEq, Eq)]
724pub enum Message {
725    Hello(Hello),
726    Welcome(Welcome),
727    RegisterServices(RegisterServices),
728    RegisterServicesResult(RegisterServicesResult),
729    ExposePort(ExposePort),
730    ExposePortResult(ExposePortResult),
731    PrepareService(PrepareService),
732    PrepareServiceResult(PrepareServiceResult),
733    UnregisterServices(UnregisterServices),
734    UnregisterServicesResult(UnregisterServicesResult),
735    ConnectStream(ConnectStream),
736    ConnectStreamResult(ConnectStreamResult),
737    OpenStream(OpenStream),
738    OpenStreamResult(OpenStreamResult),
739    DataHello(DataHello),
740    DataReady(DataReady),
741    ServiceStatus(ServiceStatus),
742    Ping(Ping),
743    Pong(Pong),
744    StreamClosed(StreamClosed),
745    Error(ErrorBody),
746}
747
748impl Message {
749    pub fn kind(&self) -> &'static str {
750        match self {
751            Self::Hello(_) => message_type::HELLO,
752            Self::Welcome(_) => message_type::WELCOME,
753            Self::RegisterServices(_) => message_type::REGISTER_SERVICES,
754            Self::RegisterServicesResult(_) => message_type::REGISTER_SERVICES_RESULT,
755            Self::ExposePort(_) => message_type::EXPOSE_PORT,
756            Self::ExposePortResult(_) => message_type::EXPOSE_PORT_RESULT,
757            Self::PrepareService(_) => message_type::PREPARE_SERVICE,
758            Self::PrepareServiceResult(_) => message_type::PREPARE_SERVICE_RESULT,
759            Self::UnregisterServices(_) => message_type::UNREGISTER_SERVICES,
760            Self::UnregisterServicesResult(_) => message_type::UNREGISTER_SERVICES_RESULT,
761            Self::ConnectStream(_) => message_type::CONNECT_STREAM,
762            Self::ConnectStreamResult(_) => message_type::CONNECT_STREAM_RESULT,
763            Self::OpenStream(_) => message_type::OPEN_STREAM,
764            Self::OpenStreamResult(_) => message_type::OPEN_STREAM_RESULT,
765            Self::DataHello(_) => message_type::DATA_HELLO,
766            Self::DataReady(_) => message_type::DATA_READY,
767            Self::ServiceStatus(_) => message_type::SERVICE_STATUS,
768            Self::Ping(_) => message_type::PING,
769            Self::Pong(_) => message_type::PONG,
770            Self::StreamClosed(_) => message_type::STREAM_CLOSED,
771            Self::Error(_) => message_type::ERROR,
772        }
773    }
774}
775
776#[derive(Clone, Debug, PartialEq, Eq)]
777pub struct ProtocolMessage {
778    pub request_id: Option<Token>,
779    pub message: Message,
780    pub extensions: Extensions,
781}
782
783impl ProtocolMessage {
784    pub fn new(message: Message) -> Self {
785        Self {
786            request_id: None,
787            message,
788            extensions: Extensions::new(),
789        }
790    }
791
792    pub fn with_request_id(mut self, request_id: Token) -> Self {
793        self.request_id = Some(request_id);
794        self
795    }
796
797    pub fn kind(&self) -> &'static str {
798        self.message.kind()
799    }
800}
801
802#[derive(Serialize)]
803struct WireEnvelopeOut {
804    #[serde(rename = "type")]
805    kind: &'static str,
806    version: u16,
807    #[serde(skip_serializing_if = "Option::is_none")]
808    request_id: Option<Token>,
809    body: serde_json::Value,
810    #[serde(skip_serializing_if = "StringMap::is_empty")]
811    extensions: Extensions,
812}
813
814#[derive(Deserialize)]
815#[serde(deny_unknown_fields)]
816struct WireEnvelopeIn {
817    #[serde(rename = "type")]
818    kind: Token,
819    version: u16,
820    #[serde(default)]
821    request_id: Option<Token>,
822    body: Box<RawValue>,
823    #[serde(default)]
824    extensions: Extensions,
825}
826
827pub fn to_json(message: &ProtocolMessage) -> Result<String> {
828    validate_message(message)?;
829    let body = body_to_value(&message.message)?;
830    let envelope = WireEnvelopeOut {
831        kind: message.kind(),
832        version: PROTOCOL_VERSION,
833        request_id: message.request_id.clone(),
834        body,
835        extensions: message.extensions.clone(),
836    };
837    Ok(serde_json::to_string(&envelope)?)
838}
839
840pub fn from_json(json: &str) -> Result<ProtocolMessage> {
841    let envelope: WireEnvelopeIn = serde_json::from_str(json)?;
842    if envelope.version != PROTOCOL_VERSION {
843        return Err(ProtocolError::UnsupportedVersion {
844            version: envelope.version,
845        });
846    }
847
848    let message = match envelope.kind.as_str() {
849        message_type::HELLO => Message::Hello(parse_body(&envelope.body)?),
850        message_type::WELCOME => Message::Welcome(parse_body(&envelope.body)?),
851        message_type::REGISTER_SERVICES => Message::RegisterServices(parse_body(&envelope.body)?),
852        message_type::REGISTER_SERVICES_RESULT => {
853            Message::RegisterServicesResult(parse_body(&envelope.body)?)
854        }
855        message_type::EXPOSE_PORT => Message::ExposePort(parse_body(&envelope.body)?),
856        message_type::EXPOSE_PORT_RESULT => Message::ExposePortResult(parse_body(&envelope.body)?),
857        message_type::PREPARE_SERVICE => Message::PrepareService(parse_body(&envelope.body)?),
858        message_type::PREPARE_SERVICE_RESULT => {
859            Message::PrepareServiceResult(parse_body(&envelope.body)?)
860        }
861        message_type::UNREGISTER_SERVICES => {
862            Message::UnregisterServices(parse_body(&envelope.body)?)
863        }
864        message_type::UNREGISTER_SERVICES_RESULT => {
865            Message::UnregisterServicesResult(parse_body(&envelope.body)?)
866        }
867        message_type::CONNECT_STREAM => Message::ConnectStream(parse_body(&envelope.body)?),
868        message_type::CONNECT_STREAM_RESULT => {
869            Message::ConnectStreamResult(parse_body(&envelope.body)?)
870        }
871        message_type::OPEN_STREAM => Message::OpenStream(parse_body(&envelope.body)?),
872        message_type::OPEN_STREAM_RESULT => Message::OpenStreamResult(parse_body(&envelope.body)?),
873        message_type::DATA_HELLO => Message::DataHello(parse_body(&envelope.body)?),
874        message_type::DATA_READY => Message::DataReady(parse_body(&envelope.body)?),
875        message_type::SERVICE_STATUS => Message::ServiceStatus(parse_body(&envelope.body)?),
876        message_type::PING => Message::Ping(parse_body(&envelope.body)?),
877        message_type::PONG => Message::Pong(parse_body(&envelope.body)?),
878        message_type::STREAM_CLOSED => Message::StreamClosed(parse_body(&envelope.body)?),
879        message_type::ERROR => Message::Error(parse_body(&envelope.body)?),
880        _ => return Err(ProtocolError::UnknownMessageType(envelope.kind)),
881    };
882
883    let message = ProtocolMessage {
884        request_id: envelope.request_id,
885        message,
886        extensions: envelope.extensions,
887    };
888    validate_message(&message)?;
889    Ok(message)
890}
891
892fn parse_body<T>(raw: &RawValue) -> Result<T>
893where
894    T: for<'de> Deserialize<'de>,
895{
896    Ok(serde_json::from_str(raw.get())?)
897}
898
899fn body_to_value(message: &Message) -> Result<serde_json::Value> {
900    match message {
901        Message::Hello(body) => Ok(serde_json::to_value(body)?),
902        Message::Welcome(body) => Ok(serde_json::to_value(body)?),
903        Message::RegisterServices(body) => Ok(serde_json::to_value(body)?),
904        Message::RegisterServicesResult(body) => Ok(serde_json::to_value(body)?),
905        Message::ExposePort(body) => Ok(serde_json::to_value(body)?),
906        Message::ExposePortResult(body) => Ok(serde_json::to_value(body)?),
907        Message::PrepareService(body) => Ok(serde_json::to_value(body)?),
908        Message::PrepareServiceResult(body) => Ok(serde_json::to_value(body)?),
909        Message::UnregisterServices(body) => Ok(serde_json::to_value(body)?),
910        Message::UnregisterServicesResult(body) => Ok(serde_json::to_value(body)?),
911        Message::ConnectStream(body) => Ok(serde_json::to_value(body)?),
912        Message::ConnectStreamResult(body) => Ok(serde_json::to_value(body)?),
913        Message::OpenStream(body) => Ok(serde_json::to_value(body)?),
914        Message::OpenStreamResult(body) => Ok(serde_json::to_value(body)?),
915        Message::DataHello(body) => Ok(serde_json::to_value(body)?),
916        Message::DataReady(body) => Ok(serde_json::to_value(body)?),
917        Message::ServiceStatus(body) => Ok(serde_json::to_value(body)?),
918        Message::Ping(body) => Ok(serde_json::to_value(body)?),
919        Message::Pong(body) => Ok(serde_json::to_value(body)?),
920        Message::StreamClosed(body) => Ok(serde_json::to_value(body)?),
921        Message::Error(body) => Ok(serde_json::to_value(body)?),
922    }
923}
924
925pub struct DecodedFrame {
926    pub payload: Vec<u8>,
927    pub consumed: usize,
928}
929
930pub fn encode_frame(payload: &[u8]) -> Result<Vec<u8>> {
931    if payload.len() > MAX_FRAME_BYTES {
932        return Err(ProtocolError::FrameTooLarge {
933            len: payload.len(),
934            max: MAX_FRAME_BYTES,
935        });
936    }
937
938    let len = payload.len() as u32;
939    let mut out = Vec::with_capacity(4 + payload.len());
940    out.extend_from_slice(&len.to_be_bytes());
941    out.extend_from_slice(payload);
942    Ok(out)
943}
944
945pub fn try_decode_frame(buffer: &[u8]) -> Result<Option<DecodedFrame>> {
946    if buffer.len() < 4 {
947        return Ok(None);
948    }
949
950    let len = u32::from_be_bytes([buffer[0], buffer[1], buffer[2], buffer[3]]) as usize;
951    if len > MAX_FRAME_BYTES {
952        return Err(ProtocolError::FrameTooLarge {
953            len,
954            max: MAX_FRAME_BYTES,
955        });
956    }
957
958    let needed = 4 + len;
959    if buffer.len() < needed {
960        return Ok(None);
961    }
962
963    Ok(Some(DecodedFrame {
964        payload: buffer[4..needed].to_vec(),
965        consumed: needed,
966    }))
967}
968
969pub fn canonical_data_signature_input(data: &DataHello) -> Vec<u8> {
970    canonical_data_signature_input_parts(
971        &data.session_id,
972        &data.share_id,
973        &data.stream_id,
974        &data.service_id,
975        &data.nonce,
976    )
977}
978
979pub fn canonical_data_signature_input_parts(
980    session_id: &Token,
981    share_id: &Token,
982    stream_id: &Token,
983    service_id: &Token,
984    nonce: &Token,
985) -> Vec<u8> {
986    let mut out = b"nexer-data-v1\0".to_vec();
987    append_len_prefixed(&mut out, session_id.as_str().as_bytes());
988    append_len_prefixed(&mut out, share_id.as_str().as_bytes());
989    append_len_prefixed(&mut out, stream_id.as_str().as_bytes());
990    append_len_prefixed(&mut out, service_id.as_str().as_bytes());
991    append_len_prefixed(&mut out, nonce.as_str().as_bytes());
992    out
993}
994
995pub fn data_signature_hex(
996    secret: &Secret,
997    session_id: &Token,
998    share_id: &Token,
999    stream_id: &Token,
1000    service_id: &Token,
1001    nonce: &Token,
1002) -> Signature {
1003    let key = hmac::Key::new(hmac::HMAC_SHA256, secret.as_str().as_bytes());
1004    let input =
1005        canonical_data_signature_input_parts(session_id, share_id, stream_id, service_id, nonce);
1006    let tag = hmac::sign(&key, &input);
1007    Signature::new(hex_lower(tag.as_ref())).expect("HMAC-SHA256 hex output is a valid signature")
1008}
1009
1010pub fn verify_data_signature(secret: &Secret, data: &DataHello) -> bool {
1011    let Some(signature) = decode_signature(data.signature.as_str()) else {
1012        return false;
1013    };
1014    let key = hmac::Key::new(hmac::HMAC_SHA256, secret.as_str().as_bytes());
1015    let input = canonical_data_signature_input(data);
1016    hmac::verify(&key, &input, &signature).is_ok()
1017}
1018
1019fn decode_signature(value: &str) -> Option<Vec<u8>> {
1020    if value.len() == Signature::HEX_SHA256_LEN {
1021        return decode_hex(value);
1022    }
1023
1024    if value.len() == Signature::BASE64URL_SHA256_LEN {
1025        return base64::engine::general_purpose::URL_SAFE_NO_PAD
1026            .decode(value)
1027            .ok();
1028    }
1029
1030    None
1031}
1032
1033fn decode_hex(value: &str) -> Option<Vec<u8>> {
1034    let mut out = Vec::with_capacity(value.len() / 2);
1035    for chunk in value.as_bytes().chunks_exact(2) {
1036        let high = hex_value(chunk[0])?;
1037        let low = hex_value(chunk[1])?;
1038        out.push((high << 4) | low);
1039    }
1040    Some(out)
1041}
1042
1043fn hex_value(byte: u8) -> Option<u8> {
1044    match byte {
1045        b'0'..=b'9' => Some(byte - b'0'),
1046        b'a'..=b'f' => Some(byte - b'a' + 10),
1047        _ => None,
1048    }
1049}
1050
1051fn hex_lower(bytes: &[u8]) -> String {
1052    const HEX: &[u8; 16] = b"0123456789abcdef";
1053    let mut out = String::with_capacity(bytes.len() * 2);
1054    for byte in bytes {
1055        out.push(HEX[(byte >> 4) as usize] as char);
1056        out.push(HEX[(byte & 0x0f) as usize] as char);
1057    }
1058    out
1059}
1060
1061fn append_len_prefixed(out: &mut Vec<u8>, value: &[u8]) {
1062    let len = value.len() as u32;
1063    out.extend_from_slice(&len.to_be_bytes());
1064    out.extend_from_slice(value);
1065}
1066
1067pub fn is_default_allowed_target(target: &Target) -> bool {
1068    is_loopback_host(target.host.as_str())
1069}
1070
1071pub fn is_loopback_host(host: &str) -> bool {
1072    host.eq_ignore_ascii_case("localhost")
1073        || host == "::1"
1074        || host == "[::1]"
1075        || is_ipv4_loopback_literal(host)
1076}
1077
1078fn is_ipv4_loopback_literal(host: &str) -> bool {
1079    let mut octets = [0_u8; 4];
1080    let mut count = 0_usize;
1081
1082    for part in host.split('.') {
1083        if count == 4 || part.is_empty() || part.len() > 3 {
1084            return false;
1085        }
1086        if !part.bytes().all(|b| b.is_ascii_digit()) {
1087            return false;
1088        }
1089        let Ok(value) = part.parse::<u8>() else {
1090            return false;
1091        };
1092        octets[count] = value;
1093        count += 1;
1094    }
1095
1096    count == 4 && octets[0] == 127
1097}
1098
1099fn validate_message(message: &ProtocolMessage) -> Result<()> {
1100    if message.extensions.0.len() > 64 {
1101        return Err(ProtocolError::InvalidField {
1102            field: "extensions",
1103            message: "too many extension entries".to_string(),
1104        });
1105    }
1106
1107    match &message.message {
1108        Message::Hello(body) => {
1109            validate_unique_tokens("features", &body.features)?;
1110            validate_unique_tokens("requested_entitlements", &body.requested_entitlements)?;
1111        }
1112        Message::RegisterServices(body) => {
1113            validate_non_empty_vec("services", &body.services)?;
1114            if body.services.len() > 128 {
1115                return Err(ProtocolError::InvalidField {
1116                    field: "services",
1117                    message: "too many services".to_string(),
1118                });
1119            }
1120            let mut seen = BTreeSet::new();
1121            for service in &body.services {
1122                if !seen.insert(&service.service_id) {
1123                    return Err(ProtocolError::InvalidField {
1124                        field: "services",
1125                        message: format!("duplicate service_id: {}", service.service_id),
1126                    });
1127                }
1128            }
1129        }
1130        Message::RegisterServicesResult(body) => {
1131            validate_unique_service_results(&body.accepted, &body.rejected)?;
1132        }
1133        Message::ExposePortResult(body) => {
1134            if body.status.as_str() == expose_port_status::REJECTED && body.error.is_none() {
1135                return Err(ProtocolError::InvalidField {
1136                    field: "error",
1137                    message: "rejected expose_port_result requires error".to_string(),
1138                });
1139            }
1140        }
1141        Message::PrepareService(body) => {
1142            if body.timeout_ms == 0 {
1143                return Err(ProtocolError::InvalidField {
1144                    field: "timeout_ms",
1145                    message: "must be non-zero".to_string(),
1146                });
1147            }
1148        }
1149        Message::PrepareServiceResult(body) => {
1150            if body.status.as_str() != prepare_service_status::READY && body.error.is_none() {
1151                return Err(ProtocolError::InvalidField {
1152                    field: "error",
1153                    message: "non-ready prepare_service_result requires error".to_string(),
1154                });
1155            }
1156        }
1157        Message::ConnectStream(body) => {
1158            if body.connect_timeout_ms == 0 {
1159                return Err(ProtocolError::InvalidField {
1160                    field: "connect_timeout_ms",
1161                    message: "must be non-zero".to_string(),
1162                });
1163            }
1164        }
1165        Message::ConnectStreamResult(body) => {
1166            if body.status.as_str() == connect_stream_status::REJECTED && body.error.is_none() {
1167                return Err(ProtocolError::InvalidField {
1168                    field: "error",
1169                    message: "rejected connect_stream_result requires error".to_string(),
1170                });
1171            }
1172        }
1173        Message::UnregisterServices(body) => {
1174            validate_non_empty_vec("service_ids", &body.service_ids)?;
1175            validate_unique_tokens("service_ids", &body.service_ids)?;
1176        }
1177        Message::OpenStreamResult(body) => {
1178            if body.status.as_str() == open_stream_status::REJECTED && body.error.is_none() {
1179                return Err(ProtocolError::InvalidField {
1180                    field: "error",
1181                    message: "rejected open_stream_result requires error".to_string(),
1182                });
1183            }
1184        }
1185        Message::Welcome(body) => {
1186            if body.heartbeat_interval_ms == 0
1187                || body.data_connect_timeout_ms == 0
1188                || body.max_concurrent_streams == 0
1189            {
1190                return Err(ProtocolError::InvalidField {
1191                    field: "welcome",
1192                    message: "timeout and capacity fields must be non-zero".to_string(),
1193                });
1194            }
1195            validate_unique_tokens("entitlements", &body.entitlements)?;
1196        }
1197        _ => {}
1198    }
1199
1200    Ok(())
1201}
1202
1203fn validate_unique_tokens(field: &'static str, tokens: &[Token]) -> Result<()> {
1204    let mut seen = BTreeSet::new();
1205    for token in tokens {
1206        if !seen.insert(token) {
1207            return Err(ProtocolError::InvalidField {
1208                field,
1209                message: format!("duplicate token: {token}"),
1210            });
1211        }
1212    }
1213    Ok(())
1214}
1215
1216fn validate_non_empty_vec<T>(field: &'static str, values: &[T]) -> Result<()> {
1217    if values.is_empty() {
1218        return Err(ProtocolError::InvalidField {
1219            field,
1220            message: "must not be empty".to_string(),
1221        });
1222    }
1223    Ok(())
1224}
1225
1226fn validate_unique_service_results(
1227    accepted: &[AcceptedService],
1228    rejected: &[RejectedService],
1229) -> Result<()> {
1230    let mut seen = BTreeSet::new();
1231    for service in accepted {
1232        if !seen.insert(&service.service_id) {
1233            return Err(ProtocolError::InvalidField {
1234                field: "accepted",
1235                message: format!("duplicate service_id: {}", service.service_id),
1236            });
1237        }
1238    }
1239    for service in rejected {
1240        if !seen.insert(&service.service_id) {
1241            return Err(ProtocolError::InvalidField {
1242                field: "rejected",
1243                message: format!("duplicate service_id: {}", service.service_id),
1244            });
1245        }
1246    }
1247    Ok(())
1248}
1249
1250fn validate_token(field: &'static str, value: &str) -> Result<()> {
1251    if value.is_empty() {
1252        return Err(ProtocolError::InvalidToken {
1253            field,
1254            reason: "must not be empty",
1255        });
1256    }
1257    if value.len() > Token::MAX_LEN {
1258        return Err(ProtocolError::InvalidToken {
1259            field,
1260            reason: "too long",
1261        });
1262    }
1263    if !value.bytes().all(is_token_byte) {
1264        return Err(ProtocolError::InvalidToken {
1265            field,
1266            reason: "contains a byte outside [A-Za-z0-9._:-]",
1267        });
1268    }
1269    Ok(())
1270}
1271
1272fn validate_signature(value: &str) -> Result<()> {
1273    if value.len() == Signature::HEX_SHA256_LEN
1274        && value
1275            .bytes()
1276            .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
1277    {
1278        return Ok(());
1279    }
1280
1281    if value.len() == Signature::BASE64URL_SHA256_LEN
1282        && value
1283            .bytes()
1284            .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_'))
1285    {
1286        return Ok(());
1287    }
1288
1289    Err(ProtocolError::InvalidField {
1290        field: "signature",
1291        message: "must be lowercase hex sha256 or unpadded base64url sha256".to_string(),
1292    })
1293}
1294
1295fn is_token_byte(byte: u8) -> bool {
1296    byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'_' | b':' | b'-')
1297}
1298
1299fn validate_bounded_string(
1300    field: &'static str,
1301    value: &str,
1302    max_len: usize,
1303    allow_empty: bool,
1304) -> Result<()> {
1305    if !allow_empty && value.is_empty() {
1306        return Err(ProtocolError::InvalidField {
1307            field,
1308            message: "must not be empty".to_string(),
1309        });
1310    }
1311    if value.len() > max_len {
1312        return Err(ProtocolError::InvalidField {
1313            field,
1314            message: "too long".to_string(),
1315        });
1316    }
1317    if value.chars().any(char::is_control) {
1318        return Err(ProtocolError::InvalidField {
1319            field,
1320            message: "must not contain control characters".to_string(),
1321        });
1322    }
1323    Ok(())
1324}
1325
1326#[cfg(test)]
1327mod tests {
1328    use super::*;
1329
1330    fn token(value: &str) -> Token {
1331        Token::new(value).unwrap()
1332    }
1333
1334    fn text(value: &str) -> Text {
1335        Text::new(value).unwrap()
1336    }
1337
1338    fn secret(value: &str) -> Secret {
1339        Secret::new(value).unwrap()
1340    }
1341
1342    fn signature(value: &str) -> Signature {
1343        Signature::new(value).unwrap()
1344    }
1345
1346    fn hello_message() -> ProtocolMessage {
1347        ProtocolMessage::new(Message::Hello(Hello {
1348            client_id: token("client-1"),
1349            agent: Agent {
1350                name: token("nexer"),
1351                version: Some(token("0.1.0")),
1352                platform: Some(token("darwin-arm64")),
1353            },
1354            auth: Auth {
1355                method: token("api_key"),
1356                api_key: secret("nexer_live_test"),
1357            },
1358            resume_session_id: None,
1359            features: vec![token("data-conn-v1"), token("dynamic-services-v1")],
1360            requested_entitlements: vec![token("tcp-forward-v1")],
1361            extensions: Extensions::new(),
1362        }))
1363    }
1364
1365    #[test]
1366    fn envelope_round_trip() {
1367        let message = hello_message();
1368        let json = to_json(&message).unwrap();
1369        assert!(json.contains("\"type\":\"hello\""));
1370        assert!(json.contains("\"version\":1"));
1371        assert!(json.contains("\"body\""));
1372
1373        let parsed = from_json(&json).unwrap();
1374        assert_eq!(parsed, message);
1375    }
1376
1377    #[test]
1378    fn request_id_lives_in_envelope() {
1379        let message = ProtocolMessage::new(Message::Ping(Ping {
1380            time: text("2026-07-13T00:00:00Z"),
1381            extensions: Extensions::new(),
1382        }))
1383        .with_request_id(token("req-1"));
1384
1385        let json = to_json(&message).unwrap();
1386        assert!(json.contains("\"request_id\":\"req-1\""));
1387        let parsed = from_json(&json).unwrap();
1388        assert_eq!(parsed.request_id.unwrap().as_str(), "req-1");
1389    }
1390
1391    #[test]
1392    fn expose_port_round_trip() {
1393        let message = ProtocolMessage::new(Message::ExposePort(ExposePort {
1394            share_id: token("share-1"),
1395            service_id: token("tcp-local"),
1396            name: text("local-tcp"),
1397            protocol: token(service_protocol::TCP),
1398            target: Target {
1399                host: text("127.0.0.1"),
1400                port: NonZeroU16::new(7000).unwrap(),
1401            },
1402            reason: token("user-request"),
1403            requested_by: token("user-2"),
1404            metadata: Metadata::new(),
1405            extensions: Extensions::new(),
1406        }))
1407        .with_request_id(token("req-expose-1"));
1408
1409        let json = to_json(&message).unwrap();
1410        assert!(json.contains("\"type\":\"expose_port\""));
1411        let parsed = from_json(&json).unwrap();
1412        assert_eq!(parsed, message);
1413    }
1414
1415    #[test]
1416    fn connect_stream_round_trip() {
1417        let message = ProtocolMessage::new(Message::ConnectStream(ConnectStream {
1418            client_id: token("app-proxy-1"),
1419            auth: Auth {
1420                method: token("api_key"),
1421                api_key: secret("nexer_live_test"),
1422            },
1423            share_id: token("share-1"),
1424            service_id: token("tcp-local"),
1425            reason: token("app-connect"),
1426            connect_timeout_ms: 10_000,
1427            metadata: Metadata::new(),
1428            extensions: Extensions::new(),
1429        }))
1430        .with_request_id(token("req-connect-1"));
1431
1432        let json = to_json(&message).unwrap();
1433        assert!(json.contains("\"type\":\"connect_stream\""));
1434        let parsed = from_json(&json).unwrap();
1435        assert_eq!(parsed, message);
1436    }
1437
1438    #[test]
1439    fn prepare_service_round_trip() {
1440        let message = ProtocolMessage::new(Message::PrepareService(PrepareService {
1441            service_id: token("service-123"),
1442            reason: token("debug-session"),
1443            requested_by: token("user-2"),
1444            timeout_ms: 180_000,
1445            metadata: Metadata::new(),
1446            extensions: Extensions::new(),
1447        }))
1448        .with_request_id(token("req-prepare-1"));
1449
1450        let json = to_json(&message).unwrap();
1451        assert!(json.contains("\"type\":\"prepare_service\""));
1452        let parsed = from_json(&json).unwrap();
1453        assert_eq!(parsed, message);
1454    }
1455
1456    #[test]
1457    fn rejects_unknown_top_level_fields() {
1458        let err = from_json(r#"{"type":"ping","version":1,"body":{"time":"now"},"extra":true}"#)
1459            .unwrap_err();
1460        assert_eq!(err.code(), error_code::BAD_FRAME);
1461    }
1462
1463    #[test]
1464    fn rejects_duplicate_known_fields() {
1465        let err =
1466            from_json(r#"{"type":"ping","version":1,"body":{"time":"a","time":"b"}}"#).unwrap_err();
1467        assert_eq!(err.code(), error_code::BAD_FRAME);
1468    }
1469
1470    #[test]
1471    fn rejects_duplicate_envelope_fields() {
1472        let err = from_json(r#"{"type":"ping","type":"pong","version":1,"body":{"time":"now"}}"#)
1473            .unwrap_err();
1474        assert_eq!(err.code(), error_code::BAD_FRAME);
1475    }
1476
1477    #[test]
1478    fn rejects_duplicate_map_keys() {
1479        let err = from_json(
1480            r#"{"type":"register_services","version":1,"request_id":"req-1","body":{"share_id":"share-1","services":[{"service_id":"tcp-local","name":"local-tcp","protocol":"tcp","target":{"host":"127.0.0.1","port":7000},"metadata":{"label":"a","label":"b"}}]}}"#,
1481        )
1482        .unwrap_err();
1483        assert_eq!(err.code(), error_code::BAD_FRAME);
1484    }
1485
1486    #[test]
1487    fn rejects_bad_tokens_at_decode_boundary() {
1488        let err = from_json(
1489            r#"{"type":"ping","version":1,"request_id":"bad token","body":{"time":"now"}}"#,
1490        )
1491        .unwrap_err();
1492        assert_eq!(err.code(), error_code::BAD_FRAME);
1493    }
1494
1495    #[test]
1496    fn unsupported_version_has_machine_code() {
1497        let err = from_json(r#"{"type":"ping","version":2,"body":{"time":"now"}}"#).unwrap_err();
1498        assert_eq!(err.code(), error_code::UNSUPPORTED_VERSION);
1499    }
1500
1501    #[test]
1502    fn unknown_message_type_is_distinct() {
1503        let err = from_json(r#"{"type":"future_message","version":1,"body":{}}"#).unwrap_err();
1504        assert_eq!(err.code(), error_code::UNKNOWN_MESSAGE_TYPE);
1505    }
1506
1507    #[test]
1508    fn open_stream_rejection_requires_error() {
1509        let message = ProtocolMessage::new(Message::OpenStreamResult(OpenStreamResult {
1510            stream_id: token("stream-1"),
1511            status: token(open_stream_status::REJECTED),
1512            error: None,
1513            extensions: Extensions::new(),
1514        }))
1515        .with_request_id(token("req-1"));
1516
1517        let err = to_json(&message).unwrap_err();
1518        assert_eq!(err.code(), error_code::BAD_FRAME);
1519    }
1520
1521    #[test]
1522    fn expose_port_rejection_requires_error() {
1523        let message = ProtocolMessage::new(Message::ExposePortResult(ExposePortResult {
1524            status: token(expose_port_status::REJECTED),
1525            service_id: token("tcp-local"),
1526            error: None,
1527            extensions: Extensions::new(),
1528        }))
1529        .with_request_id(token("req-expose-1"));
1530
1531        let err = to_json(&message).unwrap_err();
1532        assert_eq!(err.code(), error_code::BAD_FRAME);
1533    }
1534
1535    #[test]
1536    fn connect_stream_rejection_requires_error() {
1537        let message = ProtocolMessage::new(Message::ConnectStreamResult(ConnectStreamResult {
1538            stream_id: token("stream-1"),
1539            status: token(connect_stream_status::REJECTED),
1540            error: None,
1541            extensions: Extensions::new(),
1542        }))
1543        .with_request_id(token("req-connect-1"));
1544
1545        let err = to_json(&message).unwrap_err();
1546        assert_eq!(err.code(), error_code::BAD_FRAME);
1547    }
1548
1549    #[test]
1550    fn prepare_service_failure_requires_error() {
1551        let message = ProtocolMessage::new(Message::PrepareServiceResult(PrepareServiceResult {
1552            service_id: token("service-123"),
1553            status: token(prepare_service_status::FAILED),
1554            elapsed_ms: 100,
1555            error: None,
1556            extensions: Extensions::new(),
1557        }))
1558        .with_request_id(token("req-prepare-1"));
1559
1560        let err = to_json(&message).unwrap_err();
1561        assert_eq!(err.code(), error_code::BAD_FRAME);
1562    }
1563
1564    #[test]
1565    fn data_hello_accepts_strict_signature_encodings() {
1566        let hex = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
1567        assert_eq!(signature(hex).as_str(), hex);
1568
1569        let base64url = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopq";
1570        assert_eq!(signature(base64url).as_str(), base64url);
1571    }
1572
1573    #[test]
1574    fn data_hello_rejects_padded_or_standard_base64_signatures() {
1575        assert!(Signature::new("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnop=").is_err());
1576        assert!(Signature::new("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnop+").is_err());
1577        assert!(Signature::new("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnop/").is_err());
1578
1579        let err = from_json(
1580            r#"{"type":"data_hello","version":1,"body":{"client_id":"client-1","session_id":"session-1","share_id":"share-1","stream_id":"stream-1","service_id":"tcp-local","nonce":"nonce-1","signature":"bad+signature"}}"#,
1581        )
1582        .unwrap_err();
1583        assert_eq!(err.code(), error_code::BAD_FRAME);
1584    }
1585
1586    #[test]
1587    fn register_services_rejects_duplicate_service_ids() {
1588        let service = |id: &str| Service {
1589            service_id: token(id),
1590            name: text("local-tcp"),
1591            protocol: token(service_protocol::TCP),
1592            target: Target {
1593                host: text("127.0.0.1"),
1594                port: NonZeroU16::new(7000).unwrap(),
1595            },
1596            metadata: Metadata::new(),
1597            extensions: Extensions::new(),
1598        };
1599        let message = ProtocolMessage::new(Message::RegisterServices(RegisterServices {
1600            share_id: token("share-1"),
1601            services: vec![service("tcp-local"), service("tcp-local")],
1602            extensions: Extensions::new(),
1603        }))
1604        .with_request_id(token("req-register-1"));
1605
1606        let err = to_json(&message).unwrap_err();
1607        assert_eq!(err.code(), error_code::BAD_FRAME);
1608    }
1609
1610    #[test]
1611    fn register_services_rejects_duplicate_service_ids_from_json() {
1612        let err = from_json(
1613            r#"{"type":"register_services","version":1,"request_id":"req-register-1","body":{"share_id":"share-1","services":[{"service_id":"tcp-local","name":"local-tcp","protocol":"tcp","target":{"host":"127.0.0.1","port":7000}},{"service_id":"tcp-local","name":"local-tcp","protocol":"tcp","target":{"host":"127.0.0.1","port":7001}}]}}"#,
1614        )
1615        .unwrap_err();
1616        assert_eq!(err.code(), error_code::BAD_FRAME);
1617    }
1618
1619    #[test]
1620    fn frame_round_trip_and_limits() {
1621        let payload = br#"{"type":"ping","version":1,"body":{"time":"now"}}"#;
1622        let frame = encode_frame(payload).unwrap();
1623        let partial = try_decode_frame(&frame[..3]).unwrap();
1624        assert!(partial.is_none());
1625
1626        let decoded = try_decode_frame(&frame).unwrap().unwrap();
1627        assert_eq!(decoded.payload, payload);
1628        assert_eq!(decoded.consumed, frame.len());
1629
1630        let too_large = vec![b'x'; MAX_FRAME_BYTES + 1];
1631        let err = encode_frame(&too_large).unwrap_err();
1632        assert_eq!(err.code(), error_code::BAD_FRAME);
1633    }
1634
1635    #[test]
1636    fn loopback_policy_is_numeric_not_prefix_based() {
1637        let target = Target {
1638            host: text("127.0.0.1"),
1639            port: NonZeroU16::new(6379).unwrap(),
1640        };
1641        assert!(is_default_allowed_target(&target));
1642        assert!(is_loopback_host("127.1.2.3"));
1643        assert!(is_loopback_host("localhost"));
1644        assert!(is_loopback_host("::1"));
1645        assert!(!is_loopback_host("127.0.0.1.attacker.com"));
1646        assert!(!is_loopback_host("127.evil.com"));
1647        assert!(!is_loopback_host("127.0.0.256"));
1648        assert!(!is_loopback_host("10.0.0.1"));
1649    }
1650
1651    #[test]
1652    fn canonical_signature_input_is_length_prefixed() {
1653        let a = canonical_data_signature_input_parts(
1654            &token("session"),
1655            &token("share"),
1656            &token("stream"),
1657            &token("a"),
1658            &token("bc"),
1659        );
1660        let b = canonical_data_signature_input_parts(
1661            &token("session"),
1662            &token("share"),
1663            &token("stream"),
1664            &token("ab"),
1665            &token("c"),
1666        );
1667        assert_ne!(a, b);
1668        assert!(a.starts_with(b"nexer-data-v1\0"));
1669    }
1670
1671    #[test]
1672    fn data_signature_helper_round_trips_hex_and_base64url() {
1673        let secret = secret("secret-1");
1674        let mut data = DataHello {
1675            client_id: token("client-1"),
1676            session_id: token("session-1"),
1677            share_id: token("share-1"),
1678            stream_id: token("stream-1"),
1679            service_id: token("tcp-local"),
1680            nonce: token("nonce-1"),
1681            signature: data_signature_hex(
1682                &secret,
1683                &token("session-1"),
1684                &token("share-1"),
1685                &token("stream-1"),
1686                &token("tcp-local"),
1687                &token("nonce-1"),
1688            ),
1689            extensions: Extensions::new(),
1690        };
1691
1692        assert!(verify_data_signature(&secret, &data));
1693
1694        let raw = decode_signature(data.signature.as_str()).unwrap();
1695        data.signature = signature(&base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(raw));
1696        assert!(verify_data_signature(&secret, &data));
1697
1698        data.nonce = token("nonce-2");
1699        assert!(!verify_data_signature(&secret, &data));
1700    }
1701
1702    #[test]
1703    fn secret_debug_is_redacted() {
1704        let value = secret("nexer_live_test");
1705        assert_eq!(format!("{value:?}"), "Secret([redacted])");
1706    }
1707}