fips_core/
discovery.rs

1//! Bootstrap handoff types.
2//!
3//! These types model the boundary between an external rendezvous/bootstrap
4//! runtime and the core FIPS transport/handshake stack. The rendezvous side
5//! owns Nostr/STUN/UDP hole punching; once a direct UDP path is established,
6//! it hands the live socket and selected remote endpoint to FIPS so the
7//! existing Noise/FMP transport path can take over.
8
9pub mod lan;
10pub mod local;
11pub mod nostr;
12
13use crate::config::UdpConfig;
14use crate::{NodeAddr, TransportId};
15use std::net::{SocketAddr, UdpSocket};
16
17/// Punch-probe magic ("NPTC", network byte order). First byte `0x4E`
18/// collides with FMP's prefix-version high-nibble check, so the UDP
19/// transport silently filters packets carrying this magic to keep
20/// post-adoption handshake logs clean. Defined at the top-level
21/// `discovery` module so the UDP filter and the nostr submodule's
22/// punch sender share the same constant.
23pub const PUNCH_MAGIC: u32 = 0x4E505443;
24
25/// Punch-probe-ack magic ("NPTA", network byte order). Same filter as
26/// [`PUNCH_MAGIC`].
27pub const PUNCH_ACK_MAGIC: u32 = 0x4E505441;
28
29/// Returns `true` if the first four bytes of `data` match a punch-probe or
30/// punch-ack magic. Used by the UDP transport's receive loop to silently
31/// drop stray probes that arrive on an adopted socket after the remote
32/// peer's punch attempt has already timed out.
33pub fn is_punch_packet(data: &[u8]) -> bool {
34    if data.len() < 4 {
35        return false;
36    }
37    let magic = u32::from_be_bytes([data[0], data[1], data[2], data[3]]);
38    magic == PUNCH_MAGIC || magic == PUNCH_ACK_MAGIC
39}
40
41/// Result of handing an established traversal session into FIPS.
42#[derive(Debug, Clone)]
43pub struct BootstrapHandoffResult {
44    /// Newly allocated transport ID used for the adopted UDP socket.
45    pub transport_id: TransportId,
46    /// Local socket address now owned by the FIPS UDP transport.
47    pub local_addr: SocketAddr,
48    /// Confirmed remote UDP endpoint selected by traversal.
49    pub remote_addr: SocketAddr,
50    /// Peer node address derived from the supplied peer identity.
51    pub peer_node_addr: NodeAddr,
52    /// Nostr session identifier used by the bootstrap runtime.
53    pub session_id: String,
54}
55
56/// Established UDP traversal ready to be handed into FIPS.
57///
58/// The socket must already be bound and must be the same socket used for the
59/// traversal runtime's STUN and punch traffic so the NAT mapping is preserved.
60#[derive(Debug)]
61pub struct EstablishedTraversal {
62    /// Rendezvous session identifier for logging/correlation.
63    pub session_id: String,
64    /// Remote peer identity in `npub` form.
65    pub peer_npub: String,
66    /// The selected remote UDP endpoint to use for the FIPS handshake.
67    pub remote_addr: SocketAddr,
68    /// The live UDP socket carrying the established mapping.
69    pub socket: UdpSocket,
70    /// Optional name for the adopted UDP transport.
71    pub transport_name: Option<String>,
72    /// Optional UDP transport tuning overrides.
73    pub transport_config: Option<UdpConfig>,
74}
75
76impl EstablishedTraversal {
77    /// Construct an established traversal handoff.
78    pub fn new(
79        session_id: impl Into<String>,
80        peer_npub: impl Into<String>,
81        remote_addr: SocketAddr,
82        socket: UdpSocket,
83    ) -> Self {
84        Self {
85            session_id: session_id.into(),
86            peer_npub: peer_npub.into(),
87            remote_addr,
88            socket,
89            transport_name: None,
90            transport_config: None,
91        }
92    }
93
94    /// Attach an explicit transport name to the adopted UDP transport.
95    pub fn with_transport_name(mut self, name: impl Into<String>) -> Self {
96        self.transport_name = Some(name.into());
97        self
98    }
99
100    /// Override UDP transport tuning for the adopted socket.
101    pub fn with_transport_config(mut self, config: UdpConfig) -> Self {
102        self.transport_config = Some(config);
103        self
104    }
105}
fips_core/discovery.rs

fips_core/
discovery.rs
