phantom_protocol/transport/
api.rs

1//! Phantom Universal Transport Core - Public API
2//!
3//! Post-quantum secure transport layer with:
4//! - Hybrid key exchange (X25519 + Kyber768)
5//! - Hybrid signatures (Ed25519 + Dilithium3)  
6//! - Multi-path transport (KCP, TCP, FakeTLS)
7//! - Connection migration and fallback
8//!
9//! # Quick Start
10//!
11//! ```rust,ignore
12//! use phantom_protocol::transport::api::*;
13//!
14//! // Server
15//! let server = PhantomListener::bind("0.0.0.0:8080").await?;
16//! while let Ok(session) = server.accept().await {
17//!     // Session established with PQC keys
18//!     session.send(b"Hello, Phantom!").await?;
19//! }
20//!
21//! // Client
22//! let session = PhantomClient::connect("server:8080").await?;
23//! let data = session.recv().await?;
24//! ```
25
26// Re-export core types
27pub use crate::transport::scheduler::Scheduler;
28pub use crate::transport::session::{CryptoState, Session};
29pub use crate::transport::stream::Stream;
30pub use crate::transport::types::{LegType, PacketFlags, PacketHeader, SchedulerMode, SessionId};
31
32// Re-export Handshake
33pub use crate::transport::handshake::{
34    ClientHello, HandshakeClient, HandshakeError, HandshakeServer, ServerHello,
35};
36
37// Re-export crypto primitives
38pub use crate::crypto::hybrid_kem::{HybridCiphertext, HybridKeyPackage, HybridSecretKey};
39pub use crate::crypto::hybrid_sign::{
40    HybridSignError, HybridSignature, HybridSigningKey, HybridVerifyingKey,
41};
42
43/// Configuration for Phantom transport
44#[derive(Debug, Clone)]
45pub struct TransportConfig {
46    /// Enable post-quantum cryptography (default: true)
47    pub pqc_enabled: bool,
48    /// Scheduler mode for path selection
49    pub scheduler_mode: SchedulerMode,
50    /// Maximum packet size (default: 1400 bytes for KCP)
51    pub max_packet_size: usize,
52    /// Enable stealth mode for anti-DPI (default: false)
53    pub stealth_mode: bool,
54}
55
56impl Default for TransportConfig {
57    fn default() -> Self {
58        Self {
59            pqc_enabled: true,
60            scheduler_mode: SchedulerMode::LowLatency,
61            max_packet_size: 1400,
62            stealth_mode: false,
63        }
64    }
65}
66
67impl TransportConfig {
68    /// Create a config optimized for latency
69    pub fn low_latency() -> Self {
70        Self {
71            scheduler_mode: SchedulerMode::LowLatency,
72            ..Default::default()
73        }
74    }
75
76    /// Create a config optimized for high throughput
77    pub fn high_throughput() -> Self {
78        Self {
79            scheduler_mode: SchedulerMode::HighThroughput,
80            ..Default::default()
81        }
82    }
83
84    /// Create a config for stealth operation
85    pub fn stealth() -> Self {
86        Self {
87            stealth_mode: true,
88            scheduler_mode: SchedulerMode::Stealth,
89            ..Default::default()
90        }
91    }
92}
93
94/// Builder for establishing Phantom connections
95pub struct PhantomBuilder {
96    config: TransportConfig,
97    server_key: Option<HybridVerifyingKey>,
98}
99
100impl PhantomBuilder {
101    /// Create a new builder with default config
102    pub fn new() -> Self {
103        Self {
104            config: TransportConfig::default(),
105            server_key: None,
106        }
107    }
108
109    /// Set configuration
110    pub fn config(mut self, config: TransportConfig) -> Self {
111        self.config = config;
112        self
113    }
114
115    /// Pin a server's public key for verification (TOFU alternative)
116    pub fn pin_server_key(mut self, key: HybridVerifyingKey) -> Self {
117        self.server_key = Some(key);
118        self
119    }
120
121    /// Get the expected server key
122    pub fn server_key(&self) -> Option<&HybridVerifyingKey> {
123        self.server_key.as_ref()
124    }
125
126    /// Get the configuration
127    pub fn get_config(&self) -> &TransportConfig {
128        &self.config
129    }
130
131    /// Initiate a PQC handshake as client. Returns an error if the OS RNG
132    /// cannot be read.
133    pub fn create_client_handshake(
134        &self,
135    ) -> Result<HandshakeClient, crate::transport::handshake::HandshakeError> {
136        HandshakeClient::new()
137    }
138
139    /// Create a server handshake handler. Returns an error if RNG / keygen
140    /// fails.
141    pub fn create_server_handshake(
142    ) -> Result<HandshakeServer, crate::transport::handshake::HandshakeError> {
143        HandshakeServer::new()
144    }
145}
146
147impl Default for PhantomBuilder {
148    fn default() -> Self {
149        Self::new()
150    }
151}
152
153#[cfg(test)]
154mod tests {
155    use super::*;
156
157    #[test]
158    fn test_config_presets() {
159        let low_lat = TransportConfig::low_latency();
160        assert!(matches!(low_lat.scheduler_mode, SchedulerMode::LowLatency));
161
162        let high_throughput = TransportConfig::high_throughput();
163        assert!(matches!(
164            high_throughput.scheduler_mode,
165            SchedulerMode::HighThroughput
166        ));
167
168        let stealth = TransportConfig::stealth();
169        assert!(stealth.stealth_mode);
170        assert!(matches!(stealth.scheduler_mode, SchedulerMode::Stealth));
171    }
172
173    #[test]
174    fn test_builder_flow() {
175        let builder = PhantomBuilder::new().config(TransportConfig::stealth());
176
177        assert!(builder.get_config().stealth_mode);
178
179        // Create handshake components
180        let client_hs = builder
181            .create_client_handshake()
182            .expect("create_client_handshake");
183        let _client_hello = client_hs.create_client_hello();
184
185        let server_hs = PhantomBuilder::create_server_handshake().expect("create_server_handshake");
186        let _server_pk = server_hs.verifying_key();
187    }
188}
phantom_protocol/transport/api.rs

phantom_protocol/transport/
api.rs
