Merge pull request #9 from n0-computer/rae/docs-review2

add ip privacy section

Author: okdistribute

concepts/holepunching.mdx

@@ -2,7 +2,13 @@
 title: "Holepunching"
 ---
 
-When two devices want to connect directly over the internet, they face a common problem: **Network Address Translation (NAT)**. Most home and office networks use NAT, which acts like a one-way door—devices inside the network can reach out to the internet, but the internet can't easily reach back in.
+With holepunching, iroh applications can:
+- **Connect directly** between devices without manual network configuration
+- **Reduce latency** by avoiding servers when possible
+- **Save bandwidth** by keeping data transfer peer-to-peer
+- **Improve resilience and reliability** by not depending on all traffic being sent through third parties
+
+The best part? All of this happens automatically—you don't need to understand the technical details to benefit from it.
 
 ## The Problem: NAT Blocks Direct Connections
 
@@ -13,19 +19,37 @@ something you requested. The combination of NAT (which translates addresses) and
 firewall rules (which filter traffic) makes direct connections
 challenging.
 
+Most home and office networks use NAT, which acts like a one-way door—devices
+inside the network can reach out to the internet, but the internet can't easily
+reach back in. This causes reliance on central servers, which can introduce
+latency and reliability issues.
+
 Traditionally, this problem was solved by:
 - **Port forwarding**: Manually configuring your router to allow specific connections (tedious and requires technical knowledge)
 - **Relay servers**: Routing all traffic through a third-party server (slow and expensive)
 
+
 ## The Innovation: Holepunching
 
 **Holepunching** is a clever technique that works around NAT and firewall restrictions to allow direct connections between peers without manual configuration or relying entirely on relay servers.
 
-Here's how it works:
+iroh uses a sophisticated holepunching implementation built on top of QUIC and integrates with the relay system. The process relies on two key elements:
+
+Holepunching works in most network configurations, but some corporate firewalls or cellular networks may still require relay fallback. iroh handles this automatically.
+
+
+## How Holepunching Works in iroh
 
 ### 1. Initial Contact Through a Relay
 
-Both peers first connect to a shared [relay server](/concepts/relays). The relay acts as a meeting point where peers can coordinate without being able to connect directly yet.
+Both peers first connect to a shared [relay server](/concepts/relays). The relay
+acts as a meeting point where peers can coordinate without being able to connect
+directly yet.
+
+The relay server observes each node's public IP address and port (the address
+from which it sees incoming traffic). This *reflective address* can be used by
+the remote peer to reach through the firewall, provided the firewall considers
+it expected traffic.
 
 ### 2. Sharing Connection Information
 
@@ -34,6 +58,18 @@ Through the relay, peers exchange their:
 - **Port numbers** (the specific door number the router assigned them)
 - **Local addresses** (in case they're on the same network)
 
+Nodes coordinate their holepunching attempts through the relay as a side
+channel. Both nodes simultaneously send UDP datagrams to each other's reflective
+addresses. Since both are sending on the same 4-tuple (source IP, source port,
+destination IP, destination port), the firewalls recognize the incoming packets
+as matching outbound traffic and allow them through.
+
+Importantly, the relay server doesn't actively participate in holepunching -- it
+simply forwards encrypted packets between nodes without knowledge of whether
+they contain application data or coordination messages.
+
+
+
 ### 3. Simultaneous Outbound Connection
 
 Here's the magic: both peers try to connect to each other **at the same time**. When peer A sends a packet to peer B's public address, A's NAT creates a mapping and the firewall creates a temporary rule allowing responses from B. When peer B sends a packet to peer A at the same moment, B's NAT and firewall do the same.
@@ -44,25 +80,12 @@ Because both NAT mappings are established and both firewalls now have rules expe
 
 If holepunching fails (some networks use particularly strict NAT configurations), iroh automatically falls back to routing traffic through the relay server. This ensures connections always work, even if they can't be direct.
 
-## Why This Matters
-
-With holepunching, iroh applications can:
-- **Connect directly** between devices without manual network configuration
-- **Reduce latency** by avoiding relay servers when possible
-- **Save bandwidth** by keeping data transfer peer-to-peer
-- **Maintain privacy** by not routing all traffic through third parties
-
-The best part? All of this happens automatically—you don't need to understand the technical details to benefit from it.
-
-## How iroh Implements Holepunching
+## Read more
 
-iroh uses a sophisticated holepunching implementation built on top of QUIC and integrates with the relay system. For technical details on the implementation, see:
+For technical details on the implementation, see:
 
 - [iroh's holepunching implementation](https://docs.rs/iroh/latest/iroh/endpoint/index.html#nat-traversal)
 - [Relay system documentation](/concepts/relays)
 - [Dedicated infrastructure setup](/deployment/dedicated-infrastructure)
 - [Endpoint configuration](https://docs.rs/iroh/latest/iroh/endpoint/struct.Endpoint.html)
 
-<Note>
-Holepunching works in most network configurations, but some corporate firewalls or cellular networks may still require relay fallback. iroh handles this automatically.
-</Note>

deployment/security-privacy.mdx

@@ -6,7 +6,7 @@ iroh is designed with security and privacy as core principles. This document
 outlines the key security and privacy features of iroh, as well as best
 practices for deploying and using iroh in a secure manner.
 
-## End-to-End Encryption
+## Data Privacy with End-to-End Encryption
 
 All data transmitted between iroh endpoints is protected with end-to-end
 encryption. This means that data is encrypted on the sender's device and can only
@@ -23,11 +23,12 @@ endpoint creation.
 
 ## Public Relays
 
-All traffic sent through the public relays is end-to-end encrypted. The relays
-are not able to read any of the traffic that they forward or help connect.
-However, the relays are able to see metadata about connections, such as source
-and destination IP addresses, connection times, and the amount of data
-transferred.
+iroh is by default configured to use shared public infrastructure that is
+operated by [the n0 team](https://n0.computer/). Because traffic is end-to-end
+encrypted, relays are not able to read any of the traffic that they forward or
+help connect.  However, the relays are able to see metadata about connections,
+such as source and destination IP addresses, connection times, and the amount of
+relayed data.
 
 We recommend that you do not use the public relays for sensitive or confidential
 data. If you need more control over your relay infrastructure, we recommend that
@@ -36,3 +37,66 @@ you use [dedicated infrastructure](/deployment/dedicated-infrastructure) for pro
 We monitor the public relays for abuse and malicious activity. If we detect
 abuse, we reserve the right to block offending IP addresses or users from
 accessing the public relays.
+
+
+## Protecting leakage of IP Addresses 
+
+Any direct connection between two devices stands a high chance of being the fastest
+connection, but always requires IP addresses to be disclosed. As with the majority
+of the deployed internet stack today, when two endpoints establish a direct
+connection, they expose and exchange their IP addresses to each other.
+
+IP address privacy considerations are primarily relevant for consumer or peer-to-peer applications
+where strangers or untrusted parties connect directly over the internet. In these
+scenarios, developers cannot guarantee anonymity or trust between endpoints, and
+exposing IP addresses can lead to privacy risks such as location tracking or
+targeted attacks.
+
+To mitigate these risks, we recommend the following strategies to protect IP
+address privacy when using iroh, depending on your specific use case and threat model:
+
+### Basic Protection: Use dedicated infrastructure
+
+If you own the infrastructure, run your own DNS server, and
+manage the devices connecting to your network, you have control over the network
+topology and can implement appropriate security measures. We do not recommend using
+public relays for production systems, as this is shared public
+infrastructure that has no guarantees around privacy or uptime.
+
+We recommend reviewing our [dedicated
+infrastructure](/deployment/dedicated-infrastructure) guidance to set up relay
+and DNS infrastructure that fits your needs.
+
+### More protection: Use Tor or Similar Onion Routing
+
+Services like Tor provide onion routing, which encrypts packet metadata for each
+relay in the route. This offers strong IP privacy guarantees through multi-hop
+routing with layered encryption.
+
+### Upcoming
+
+#### Relay-Only Mode 
+
+Upcoming releases of iroh will support disabling hole-punching to send all traffic
+exclusively through relays. This provides IP privacy with some important caveats:
+
+- **Single-hop routing**: Traffic passes through one relay, not multiple hops
+- **Trust required**: The relay operator can technically see which endpoints are
+  communicating and their IP addresses
+- **Data remains encrypted**: The relay cannot read the actual content due to
+  end-to-end encryption
+
+This mode is suitable when you trust your relay infrastructure but still want to
+avoid direct IP exposure between endpoints.
+
+#### Multi-Hop Relay Routing
+
+We've explored the possibility of adding multi-hop relay routing to iroh. While
+technically feasible, this feature is not currently on the near-term roadmap.
+
+It's important to note that even with multi-hop relay routing, this would not be
+equivalent to onion routing. True onion routing requires encrypting packet metadata
+for each relay in the route, which would require significant protocol changes.
+
+If these features are interesting to you, please [contact us](https://n0.computer/)
+to discuss your specific requirements.