1#![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 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 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 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}