feat: best-effort UPnP IGD port mapping

Cargo.toml

@@ -39,11 +39,18 @@ exclude = [
 [features]
 # Default features include essential functionality with 100% PQC support
 # v0.15.0: Simplified feature flags - crypto is always enabled
-default = ["platform-verifier", "network-discovery"]
+default = ["platform-verifier", "network-discovery", "upnp"]
 
 # Platform-specific certificate verification
 platform-verifier = ["dep:rustls-platform-verifier"]
 
+# UPnP IGD port mapping for best-effort NAT traversal assistance.
+# When enabled, the endpoint will opportunistically request a UDP port
+# mapping from a local Internet Gateway Device. Failure is silent and
+# non-fatal — the endpoint behaves identically to a non-UPnP build when
+# no gateway is available.
+upnp = ["dep:igd-next"]
+
 # Configure `tracing` to log events via `log` if no `tracing` subscriber exists
 log = ["tracing/log"]
 
@@ -113,6 +120,12 @@ rustls-post-quantum = { version = "0.2", features = ["aws-lc-rs-unstable"] }
 socket2 = { version = "0.5", optional = true }
 nix = { version = "0.29", features = ["resource", "net"], optional = true }
 
+# UPnP IGD port mapping (optional)
+# Used by the `upnp` feature for best-effort UDP port mapping. The
+# implementation never blocks startup and silently degrades when the
+# router does not support or has disabled UPnP IGD.
+igd-next = { version = "0.17", default-features = false, features = ["aio_tokio"], optional = true }
+
 # BLE transport dependencies (cross-platform, optional)
 # btleplug supports Linux (BlueZ), macOS (Core Bluetooth), and Windows (WinRT)
 btleplug = { version = "0.11", optional = true }

benches/nat_traversal.rs

@@ -565,6 +565,7 @@ fn bench_pair_generation(c: &mut Criterion) {
                             CandidateSource::Observed { .. } => 1,
                             CandidateSource::Peer => 2,
                             CandidateSource::Predicted => 3,
+                            CandidateSource::PortMapped => 4,
                         };
 
                         for remote in &remote_candidates {
@@ -585,6 +586,7 @@ fn bench_pair_generation(c: &mut Criterion) {
                                     CandidateSource::Observed { .. } => 1,
                                     CandidateSource::Peer => 2,
                                     CandidateSource::Predicted => 3,
+                                    CandidateSource::PortMapped => 4,
                                 };
 
                                 // Calculate priority

src/bin/saorsa-transport.rs

@@ -170,6 +170,14 @@ struct Args {
     /// Chunk size for data generation/verification (bytes)
     #[arg(long, default_value = "65536")]
     chunk_size: usize,
+
+    /// Disable best-effort UPnP IGD port mapping. By default the endpoint
+    /// asks the local router to forward its UDP port — pass this flag to
+    /// skip the UPnP probe entirely (useful when the router is known to
+    /// be hostile or when running on infrastructure that does not need
+    /// it). NAT traversal still works without UPnP via hole punching.
+    #[arg(long)]
+    no_upnp: bool,
 }
 
 /// CLI subcommands
@@ -371,6 +379,15 @@ async fn main() -> anyhow::Result<()> {
     }
     // v0.13.0: No mode-based NAT config - all nodes are symmetric
 
+    if args.no_upnp {
+        let nat = saorsa_transport::unified_config::NatConfig {
+            upnp: saorsa_transport::upnp::UpnpConfig::disabled(),
+            ..saorsa_transport::unified_config::NatConfig::default()
+        };
+        builder = builder.nat(nat);
+        info!("UPnP IGD port mapping disabled (--no-upnp)");
+    }
+
     let config = builder.build()?;
 
     // Create endpoint