docs: enhance documentation for STUN NAT traversal features and examples across all relevant markdown files

Author: yosebyte

docs/en/configuration.md

@@ -62,8 +62,13 @@ For client instances, the `mode` parameter controls the connection strategy:
 
 - **Mode 1**: Force single-end forwarding mode
   - Binds to tunnel address locally and forwards traffic directly to target
-  - Uses direct connection establishment for high performance
+  - Uses direct connection establishment for high performance forwarding
   - No handshake with server required
+  - **Hybrid Mode**: If local binding fails, automatically enables STUN NAT traversal
+    - Uses the tunnel address as the STUN server address
+    - Discovers external (public) IP:port through STUN protocol
+    - Enables services behind NAT to be accessed without port forwarding
+    - Suitable for home servers, IoT devices, and peer-to-peer scenarios
 
 - **Mode 2**: Force dual-end handshake mode
   - Always connects to remote server for tunnel establishment
@@ -321,6 +326,60 @@ nodepass "client://127.0.0.1:3306/db-primary.local:3306,db-secondary.local:3306?
 # nodepass "server://host1:10101,host2:10101/target:8080"  # ✗ Wrong usage
 ```
 
+## STUN NAT Traversal
+
+NodePass client mode 1 supports automatic NAT traversal using the STUN (Session Traversal Utilities for NAT) protocol. When the client cannot bind to the specified tunnel address, it automatically enables hybrid mode with STUN support.
+
+### How STUN NAT Traversal Works
+
+1. **Automatic Fallback**: When binding to the tunnel address fails, NodePass attempts STUN discovery
+2. **STUN Server Discovery**: The tunnel address in the client URL is used as the STUN server address
+3. **Public Endpoint Discovery**: Client queries the STUN server to discover its public IP and port
+4. **Local Binding**: Client binds to a random local port and logs the NAT mapping
+5. **External Access**: External clients can connect to the discovered public endpoint
+
+### Recommended STUN Servers
+
+Google provides free public STUN servers that work well with NodePass:
+
+- `stun.l.google.com:19302` (Primary)
+- `stun1.l.google.com:19302`
+- `stun2.l.google.com:19302`
+- `stun3.l.google.com:19302`
+- `stun4.l.google.com:19302`
+
+### STUN Configuration Examples
+
+```bash
+# Use Google's primary STUN server for NAT traversal
+nodepass "client://stun.l.google.com:19302/localhost:8080?mode=1"
+
+# Expose SSH service behind NAT
+nodepass "client://stun1.l.google.com:19302/localhost:22?mode=1&log=info"
+
+# Home web server with STUN NAT traversal
+nodepass "client://stun2.l.google.com:19302/192.168.1.100:80?mode=1"
+
+# IoT device management behind NAT
+nodepass "client://stun3.l.google.com:19302/127.0.0.1:8883?mode=1&log=event"
+```
+
+### STUN Use Cases
+
+- **Home Servers**: Access home services without router port forwarding
+- **IoT Devices**: Connect to devices behind carrier-grade NAT (CGNAT)
+- **Peer-to-Peer Applications**: Direct connections between clients behind NAT
+- **Development Testing**: Test applications with external accessibility
+- **Remote Access**: Secure access to services in restricted network environments
+
+### Important Notes
+
+- STUN only discovers the public endpoint; the NAT must allow incoming connections
+- Symmetric NAT may prevent successful connections even with STUN discovery
+- The discovered public endpoint is logged: `External endpoint: <public_ip:port> -> <local_ip:port> -> <target>`
+- STUN traffic is unencrypted; only used for endpoint discovery, not data transfer
+- Other mode 1 features remain fully functional with STUN
+
 ## URL Query Parameter Scope and Applicability
 
 NodePass allows flexible configuration via URL query parameters. The following table shows which parameters are applicable in server, client, and master modes:

docs/en/examples.md

@@ -194,9 +194,73 @@ This configuration:
 
 ## IoT Device Management
 
-### Example 12: IoT Gateway
+### Example 12: IoT Gateway with STUN NAT Traversal
 
-Create a central access point for IoT devices:
+Create a central access point for IoT devices behind NAT without port forwarding:
+
+```bash
+# IoT device behind home router - expose web interface
+nodepass "client://stun.l.google.com:19302/127.0.0.1:80?mode=1&log=info"
+
+# IoT device with MQTT broker behind CGNAT
+nodepass "client://stun1.l.google.com:19302/127.0.0.1:1883?mode=1&log=event"
+
+# Smart home hub with multiple services
+nodepass "client://stun2.l.google.com:19302/192.168.1.100:8080?mode=1"
+```
+
+This configuration:
+- Enables secure connections from distributed IoT devices to external clients
+- Uses Google's STUN servers to discover public endpoints
+- Allows embedded devices to expose their local interfaces without router configuration
+- Automatically handles NAT traversal for devices behind carrier-grade NAT
+- Logs the external endpoint for connecting from outside: `External endpoint: <public_ip:port> -> <local_ip:port> -> <target>`
+
+### Example 13: Home Server Access Through NAT
+
+Access home services without opening router ports:
+
+```bash
+# Home NAS file server
+nodepass "client://stun3.l.google.com:19302/localhost:445?mode=1&log=info"
+
+# Home media server (Plex, Jellyfin, etc.)
+nodepass "client://stun4.l.google.com:19302/127.0.0.1:32400?mode=1"
+
+# Home automation server
+nodepass "client://stun.l.google.com:19302/192.168.1.50:8123?mode=1&log=event"
+```
+
+This setup:
+- Provides external access to home services without DMZ or port forwarding
+- Maintains security by avoiding router configuration changes
+- Works with dynamic IP addresses from ISPs
+- Suitable for residential internet connections with NAT
+
+### Example 14: Remote Development Environment
+
+Enable remote access to development servers behind NAT:
+
+```bash
+# Development web server behind corporate NAT
+nodepass "client://stun1.l.google.com:19302/localhost:3000?mode=1&log=debug"
+
+# Database development instance
+nodepass "client://stun2.l.google.com:19302/127.0.0.1:5432?mode=1"
+
+# API development server with hot reload
+nodepass "client://stun3.l.google.com:19302/localhost:8080?mode=1&log=info"
+```
+
+This configuration:
+- Allows team members to access development environments remotely
+- Works through corporate NAT and firewall restrictions
+- No VPN or complex network configuration required
+- Ideal for distributed development teams
+
+### Example 15: Traditional IoT Gateway (Dual-End Mode)
+
+Create a central management server for traditional tunneling scenarios:
 
 ```bash
 # Central management server
@@ -212,9 +276,74 @@ This configuration:
 - Allows embedded devices to expose their local web interfaces securely
 - Centralizes device management through a single endpoint
 
+## STUN NAT Traversal for Remote Access
+
+### Example 16: SSH Access Behind NAT
+
+Provide SSH access to machines behind NAT without port forwarding:
+
+```bash
+# Home computer SSH access
+nodepass "client://stun.l.google.com:19302/localhost:22?mode=1&log=info"
+
+# Raspberry Pi SSH behind carrier-grade NAT
+nodepass "client://stun1.l.google.com:19302/127.0.0.1:22?mode=1"
+
+# Remote server behind corporate firewall
+nodepass "client://stun2.l.google.com:19302/192.168.1.10:22?mode=1&log=event"
+```
+
+This setup:
+- Enables SSH access without router configuration or VPN
+- Works through carrier-grade NAT (CGNAT) that blocks port forwarding
+- Maintains security with SSH's built-in authentication
+- Ideal for remote system administration and troubleshooting
+
+### Example 17: Game Server Hosting Behind NAT
+
+Host game servers from home networks without port forwarding:
+
+```bash
+# Minecraft server behind NAT
+nodepass "client://stun3.l.google.com:19302/localhost:25565?mode=1&log=info"
+
+# Counter-Strike server
+nodepass "client://stun4.l.google.com:19302/127.0.0.1:27015?mode=1"
+
+# Terraria server with NAT traversal
+nodepass "client://stun.l.google.com:19302/192.168.1.100:7777?mode=1&log=event"
+```
+
+This configuration:
+- Allows hosting game servers from residential connections
+- No need for router port forwarding or DMZ setup
+- Works with dynamic IP addresses
+- Players connect to the discovered public endpoint
+
+### Example 18: VoIP and Real-Time Communication
+
+Enable peer-to-peer VoIP and communication services behind NAT:
+
+```bash
+# SIP server behind NAT
+nodepass "client://stun1.l.google.com:19302/localhost:5060?mode=1&log=info"
+
+# Mumble voice chat server
+nodepass "client://stun2.l.google.com:19302/127.0.0.1:64738?mode=1"
+
+# TeamSpeak server with NAT traversal
+nodepass "client://stun3.l.google.com:19302/192.168.1.50:9987?mode=1&log=event"
+```
+
+This setup:
+- Provides external access to VoIP and voice chat servers
+- Eliminates need for complex NAT traversal in the application itself
+- Works with existing SIP phones and voice chat clients
+- Suitable for home offices and small businesses
+
 ## Multi-environment Development
 
-### Example 13: Development Environment Access
+### Example 19: Development Environment Access
 
 Access different development environments through tunnels:
 
@@ -237,7 +366,7 @@ This setup:
 
 ## High Availability and Load Balancing
 
-### Example 14: Multi-Backend Server Load Balancing
+### Example 20: Multi-Backend Server Load Balancing
 
 Use target address groups for even traffic distribution and automatic failover:
 

docs/en/troubleshooting.md

@@ -78,6 +78,96 @@ This guide helps you diagnose and resolve common issues you might encounter when
    - Adjust `max` parameter and `NP_SEMAPHORE_LIMIT` to handle the load
    - Consider scaling horizontally with multiple NodePass instances
 
+## STUN NAT Traversal Issues
+
+### STUN Discovery Fails
+
+**Symptoms**: Client cannot discover external endpoint, or hybrid mode fails with STUN errors.
+
+**Possible Causes and Solutions**:
+
+1. **STUN Server Unreachable**
+   - Verify the STUN server address is correct and accessible
+   - Test connectivity: `nc -u stun.l.google.com 19302`
+   - Try alternative STUN servers (stun1-4.l.google.com:19302)
+   - Check if UDP traffic is blocked by firewall or ISP
+
+2. **Invalid STUN Response**
+   - Ensure the server at the tunnel address is a valid STUN server
+   - Google's STUN servers: stun.l.google.com, stun1-4.l.google.com (port 19302)
+   - STUN response must contain XOR-MAPPED-ADDRESS attribute
+   - Check for network middleware interfering with UDP packets
+
+3. **UDP Port Blocking**
+   - Verify UDP traffic is not blocked by local firewall
+   - Check router/firewall settings for UDP restrictions
+   - Some corporate networks block all UDP traffic
+   - Try using a different network (mobile hotspot) for testing
+
+4. **Timeout Issues**
+   - STUN discovery uses `NP_UDP_READ_TIMEOUT` (default: 3s)
+   - Increase timeout if network latency is high
+   - Check for packet loss affecting STUN request/response
+
+### NAT Prevents External Connections
+
+**Symptoms**: STUN discovers external endpoint but external clients cannot connect.
+
+**Possible Causes and Solutions**:
+
+1. **Symmetric NAT**
+   - Symmetric NAT creates different mappings for different remote endpoints
+   - STUN can discover the endpoint but connections from other IPs fail
+   - Check NAT type: use online NAT detection tools
+   - Consider using dual-end handshake mode (mode=2) with a server instead
+
+2. **Port Restricted NAT**
+   - NAT only allows connections from IPs that the client has contacted first
+   - This is a security feature of many consumer routers
+   - Solution: Have both peers perform STUN discovery and exchange endpoints
+   - Or use server relay mode (mode=2) for guaranteed connectivity
+
+3. **Firewall Rules**
+   - Local firewall may block incoming connections even with STUN
+   - Check iptables/Windows Firewall rules for the discovered port
+   - Allow incoming UDP/TCP traffic on the mapped port
+   - Verify with: `netstat -tuln | grep <port>`
+
+4. **Dynamic Port Mapping**
+   - Some NATs change port mapping after period of inactivity
+   - The discovered endpoint may become invalid
+   - Implement periodic keepalive traffic to maintain mapping
+   - Consider restarting NodePass to rediscover endpoint
+
+### Hybrid Mode Not Activating
+
+**Symptoms**: Client in mode=1 doesn't fallback to STUN when local binding fails.
+
+**Possible Causes and Solutions**:
+
+1. **Port Already in Use**
+   - If local port is in use, binding fails as expected
+   - Check: `netstat -tuln | grep <port>`
+   - Release the port or choose a different tunnel address
+   - Hybrid mode should activate automatically after binding failure
+
+2. **Permission Issues**
+   - Binding to ports <1024 requires root/administrator privileges
+   - Use higher port numbers (>1024) for regular users
+   - Or run NodePass with elevated privileges: `sudo nodepass ...`
+
+3. **Configuration Error**
+   - Ensure tunnel address points to a valid STUN server
+   - Format: `client://stun.l.google.com:19302/target:port?mode=1`
+   - Check logs for STUN-related error messages
+   - Verify mode is set to 1 or 0 (auto) for hybrid mode support
+
+4. **Network Interface Issues**
+   - Binding may fail due to network interface not available
+   - Check network connectivity: `ip addr` or `ifconfig`
+   - Ensure the system has an active network connection
+   - Try binding to 0.0.0.0 instead of specific interface
+
 ## Certificate Issues
 
 ### TLS Handshake Failures

docs/en/usage.md

@@ -134,6 +134,15 @@ Client mode supports automatic mode detection or forced mode selection through t
 4. No handshake with server required, enables point-to-point direct forwarding
 5. Suitable for local proxy and simple forwarding scenarios
 
+**Mode 1 with STUN NAT Traversal (Hybrid Mode)**:
+When the client cannot bind to the specified tunnel address, NodePass automatically enables hybrid mode:
+1. Discovers external (public) endpoint using STUN protocol
+2. The STUN server address is derived from the tunnel address specified in the client URL
+3. Binds to a local random port and obtains the NAT-mapped public IP:port
+4. Enables external access to services behind NAT without port forwarding
+5. Logs the mapping: `External endpoint: <public_ip:port> -> <local_ip:port> -> <target>`
+6. Suitable for peer-to-peer connections, home servers, and IoT devices behind NAT
+
 **Mode 2: Dual-End Handshake Mode**
 - **Client Receives Traffic** (when server sends traffic)
   1. Connects to the server's TCP tunnel endpoint (control channel)
@@ -155,6 +164,9 @@ nodepass "client://127.0.0.1:1080/target.example.com:8080?log=debug"
 # Force single-end forwarding mode - High performance local proxy
 nodepass "client://127.0.0.1:1080/target.example.com:8080?mode=1&log=debug"
 
+# STUN NAT traversal - Use Google's STUN server for public endpoint discovery
+nodepass "client://stun.l.google.com:19302/local.service:8080?mode=1&log=info"
+
 # Force dual-end handshake mode - Connect to NodePass server and adopt its TLS security policy
 nodepass "client://server.example.com:10101/127.0.0.1:8080?mode=2"
 
@@ -163,6 +175,9 @@ nodepass "client://server.example.com:10101/192.168.1.100:8080?log=debug&min=128
 
 # Resource-constrained configuration with forced mode
 nodepass "client://server.example.com:10101/127.0.0.1:8080?mode=2&min=16&log=info"
+
+# Resource-constrained configuration - Small connection pool
+nodepass "client://server.example.com:10101/127.0.0.1:8080?min=16&log=info"
 ```
 
 ### Master Mode (API)