phantom_protocol/transport/
api.rs

1//! Phantom Protocol — legacy transport-config / builder surface.
2//!
3//! This module re-exports the low-level transport + crypto types and offers a
4//! `TransportConfig` / `PhantomBuilder` for constructing handshake handlers
5//! directly. It predates the unified PhantomUDP rewrite: several of its knobs
6//! (`SchedulerMode`, `max_packet_size`, `stealth_mode`) reflect the old
7//! multipath/KCP design and no longer steer the live data plane (the scheduler is
8//! vestigial — see `SchedulerMode`). It is retained for the handful of in-crate
9//! callers that build raw `HandshakeClient` / `HandshakeServer` instances.
10//!
11//! The actual user-facing API is in [`crate::api`]: `PhantomListener::bind` /
12//! `accept` on the server, `PhantomSession::connect_with_transport` /
13//! `connect_pinned` on the client. New code should use those, not this module.
14
15// Re-export core types
16pub use crate::transport::scheduler::Scheduler;
17pub use crate::transport::session::{CryptoState, Session};
18pub use crate::transport::stream::Stream;
19pub use crate::transport::types::{LegType, PacketFlags, PacketHeader, SchedulerMode, SessionId};
20
21// Re-export Handshake
22pub use crate::transport::handshake::{
23    ClientHello, HandshakeClient, HandshakeError, HandshakeServer, ServerHello,
24};
25
26// Re-export crypto primitives
27pub use crate::crypto::hybrid_kem::{HybridCiphertext, HybridKeyPackage, HybridSecretKey};
28pub use crate::crypto::hybrid_sign::{
29    HybridSignError, HybridSignature, HybridSigningKey, HybridVerifyingKey,
30};
31
32/// Configuration for Phantom Protocol transport
33#[derive(Debug, Clone)]
34pub struct TransportConfig {
35    /// Enable post-quantum cryptography (default: true)
36    pub pqc_enabled: bool,
37    /// Scheduler mode for path selection
38    pub scheduler_mode: SchedulerMode,
39    /// Maximum packet size hint (default: 1400 bytes). Legacy knob — the live
40    /// PhantomUDP path uses its own `PATH_MTU` (1200) and does not read this.
41    pub max_packet_size: usize,
42    /// Enable stealth mode for anti-DPI (default: false)
43    pub stealth_mode: bool,
44}
45
46impl Default for TransportConfig {
47    fn default() -> Self {
48        Self {
49            pqc_enabled: true,
50            scheduler_mode: SchedulerMode::LowLatency,
51            max_packet_size: 1400,
52            stealth_mode: false,
53        }
54    }
55}
56
57impl TransportConfig {
58    /// Create a config optimized for latency
59    pub fn low_latency() -> Self {
60        Self {
61            scheduler_mode: SchedulerMode::LowLatency,
62            ..Default::default()
63        }
64    }
65
66    /// Create a config optimized for high throughput
67    pub fn high_throughput() -> Self {
68        Self {
69            scheduler_mode: SchedulerMode::HighThroughput,
70            ..Default::default()
71        }
72    }
73
74    /// Create a config for stealth operation
75    pub fn stealth() -> Self {
76        Self {
77            stealth_mode: true,
78            scheduler_mode: SchedulerMode::Stealth,
79            ..Default::default()
80        }
81    }
82}
83
84/// Builder for establishing Phantom Protocol connections
85pub struct PhantomBuilder {
86    config: TransportConfig,
87    server_key: Option<HybridVerifyingKey>,
88}
89
90impl PhantomBuilder {
91    /// Create a new builder with default config
92    pub fn new() -> Self {
93        Self {
94            config: TransportConfig::default(),
95            server_key: None,
96        }
97    }
98
99    /// Set configuration
100    pub fn config(mut self, config: TransportConfig) -> Self {
101        self.config = config;
102        self
103    }
104
105    /// Pin a server's public key for verification (TOFU alternative)
106    pub fn pin_server_key(mut self, key: HybridVerifyingKey) -> Self {
107        self.server_key = Some(key);
108        self
109    }
110
111    /// Get the expected server key
112    pub fn server_key(&self) -> Option<&HybridVerifyingKey> {
113        self.server_key.as_ref()
114    }
115
116    /// Get the configuration
117    pub fn get_config(&self) -> &TransportConfig {
118        &self.config
119    }
120
121    /// Initiate a PQC handshake as client. Returns an error if the OS RNG
122    /// cannot be read.
123    pub fn create_client_handshake(
124        &self,
125    ) -> Result<HandshakeClient, crate::transport::handshake::HandshakeError> {
126        HandshakeClient::new()
127    }
128
129    /// Create a server handshake handler. Returns an error if RNG / keygen
130    /// fails.
131    pub fn create_server_handshake(
132    ) -> Result<HandshakeServer, crate::transport::handshake::HandshakeError> {
133        HandshakeServer::new()
134    }
135}
136
137impl Default for PhantomBuilder {
138    fn default() -> Self {
139        Self::new()
140    }
141}
142
143#[cfg(test)]
144mod tests {
145    use super::*;
146
147    #[test]
148    fn test_config_presets() {
149        let low_lat = TransportConfig::low_latency();
150        assert!(matches!(low_lat.scheduler_mode, SchedulerMode::LowLatency));
151
152        let high_throughput = TransportConfig::high_throughput();
153        assert!(matches!(
154            high_throughput.scheduler_mode,
155            SchedulerMode::HighThroughput
156        ));
157
158        let stealth = TransportConfig::stealth();
159        assert!(stealth.stealth_mode);
160        assert!(matches!(stealth.scheduler_mode, SchedulerMode::Stealth));
161    }
162
163    #[test]
164    fn test_builder_flow() {
165        let builder = PhantomBuilder::new().config(TransportConfig::stealth());
166
167        assert!(builder.get_config().stealth_mode);
168
169        // Create handshake components
170        let client_hs = builder
171            .create_client_handshake()
172            .expect("create_client_handshake");
173        let _client_hello = client_hs.create_client_hello();
174
175        let server_hs = PhantomBuilder::create_server_handshake().expect("create_server_handshake");
176        let _server_pk = server_hs.verifying_key();
177    }
178}
phantom_protocol/transport/api.rs

phantom_protocol/transport/
api.rs
