feat: add Tor SOCKS5 proxy support for outbound .onion connections

Cherry-picks the approach from upstream ldk-node PR lightningdevkit#778 but implements
the SOCKS5 protocol directly in connection.rs instead of depending on
lightning-net-tokio::tor_connect_outbound (which requires rust-lightning
main, not available in v0.2.0).

Changes:
- Add tor_proxy_address field to Config
- Add set_tor_proxy_address() to NodeBuilder and ArcedNodeBuilder
- Add SOCKS5 connect function with Tor stream isolation (RFC 1929)
- Route OnionV3 peer connections through the SOCKS5 proxy
- Add base32 encoder for deriving .onion hostnames from pubkeys
- Expose set_tor_proxy_address in UDL bindings

Based on: lightningdevkit#778

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: AOrobator

bindings/ldk_node.udl

@@ -104,6 +104,8 @@ interface Builder {
 	[Throws=BuildError]
 	void set_announcement_addresses(sequence<SocketAddress> announcement_addresses);
 	[Throws=BuildError]
+	void set_tor_proxy_address(string tor_proxy_address);
+	[Throws=BuildError]
 	void set_node_alias(string node_alias);
 	[Throws=BuildError]
 	void set_async_payments_role(AsyncPaymentsRole? role);

src/builder.rs

@@ -1316,11 +1316,15 @@ impl ArcedNodeBuilder {
 
 	/// Set the address which [`Node`] will use as a Tor proxy to connect to peer OnionV3 addresses.
 	///
-	/// **Note**: If unset, connecting to peer OnionV3 addresses will fail.
+	/// The address should be in `host:port` format (e.g., `"127.0.0.1:9050"`).
 	///
-	/// [`tor_proxy_address`]: Config::tor_proxy_address
-	pub fn set_tor_proxy_address(&mut self, tor_proxy_address: core::net::SocketAddr) {
-		self.config.tor_proxy_address = Some(tor_proxy_address);
+	/// **Note**: If unset, connecting to peer OnionV3 addresses will fail.
+	pub fn set_tor_proxy_address(&self, tor_proxy_address: String) -> Result<(), BuildError> {
+		let addr: core::net::SocketAddr = tor_proxy_address
+			.parse()
+			.map_err(|_| BuildError::InvalidListeningAddresses)?;
+		self.inner.write().unwrap().set_tor_proxy_address(addr);
+		Ok(())
 	}
 
 	/// Sets the node alias that will be used when broadcasting announcements to the gossip

src/connection.rs

@@ -13,12 +13,17 @@ use std::time::Duration;
 
 use bitcoin::secp256k1::PublicKey;
 use lightning::ln::msgs::SocketAddress;
-use lightning::sign::RandomBytes;
+use lightning::sign::{EntropySource, RandomBytes};
+
+use tokio::io::{AsyncReadExt, AsyncWriteExt};
+use tokio::net::TcpStream;
 
 use crate::logger::{log_error, log_info, LdkLogger};
 use crate::types::PeerManager;
 use crate::Error;
 
+const TOR_CONNECT_OUTBOUND_TIMEOUT: u64 = 30;
+
 pub(crate) struct ConnectionManager<L: Deref + Clone + Sync + Send>
 where
 	L::Target: LdkLogger,
@@ -90,13 +95,27 @@ where
 				self.propagate_result_to_subscribers(&node_id, Err(Error::InvalidSocketAddress));
 				Error::InvalidSocketAddress
 			})?;
-			let connection_future = lightning_net_tokio::tor_connect_outbound(
-				Arc::clone(&self.peer_manager),
-				node_id,
-				addr.clone(),
-				proxy_addr,
-				self.tor_proxy_rng.clone(),
-			);
+			let rng = self.tor_proxy_rng.clone();
+			let pm = Arc::clone(&self.peer_manager);
+			let addr_clone = addr.clone();
+			let connection_future = async move {
+				let connect_fut = async {
+					tor_socks5_connect(addr_clone.clone(), proxy_addr, &*rng)
+						.await
+						.map(|s| s.into_std().unwrap())
+				};
+				match tokio::time::timeout(
+					Duration::from_secs(TOR_CONNECT_OUTBOUND_TIMEOUT),
+					connect_fut,
+				)
+				.await
+				{
+					Ok(Ok(stream)) => {
+						Some(lightning_net_tokio::setup_outbound(pm, node_id, stream))
+					},
+					_ => None,
+				}
+			};
 			self.await_connection(connection_future, node_id, addr).await
 		} else {
 			let socket_addr = addr
@@ -201,3 +220,173 @@ where
 		}
 	}
 }
+
+/// Connect to a peer's SocketAddress through a Tor SOCKS5 proxy.
+/// Uses Tor stream isolation via username/password auth (RFC 1929 + Tor extensions).
+async fn tor_socks5_connect<ES: Deref>(
+	addr: SocketAddress, tor_proxy_addr: core::net::SocketAddr, entropy_source: ES,
+) -> Result<TcpStream, ()>
+where
+	ES::Target: EntropySource,
+{
+	use std::io::Write;
+
+	// SOCKS5 constants (RFC 1928 / RFC 1929)
+	const VERSION: u8 = 5;
+	const NMETHODS: u8 = 1;
+	const USERNAME_PASSWORD_AUTH: u8 = 2;
+	const METHOD_SELECT_REPLY_LEN: usize = 2;
+	const USERNAME_PASSWORD_VERSION: u8 = 1;
+	const USERNAME_PASSWORD_REPLY_LEN: usize = 2;
+	const CMD_CONNECT: u8 = 1;
+	const RSV: u8 = 0;
+	const ATYP_DOMAINNAME: u8 = 3;
+	const ATYP_IPV4: u8 = 1;
+	const ATYP_IPV6: u8 = 4;
+	const SUCCESS: u8 = 0;
+
+	// Tor extensions for stream isolation
+	const USERNAME: &[u8] = b"<torS0X>0";
+	const USERNAME_LEN: usize = USERNAME.len();
+	const PASSWORD_ENTROPY_LEN: usize = 32;
+	const PASSWORD_LEN: usize = PASSWORD_ENTROPY_LEN * 2; // hex-encoded
+
+	const IPV4_ADDR_LEN: usize = 4;
+	const IPV6_ADDR_LEN: usize = 16;
+	const HOSTNAME_MAX_LEN: usize = u8::MAX as usize;
+
+	const USERNAME_PASSWORD_REQUEST_LEN: usize =
+		1 + 1 + USERNAME_LEN + 1 + PASSWORD_LEN;
+	const SOCKS5_REQUEST_MAX_LEN: usize =
+		1 + 1 + 1 + 1 + 1 + HOSTNAME_MAX_LEN + 2;
+	const SOCKS5_REPLY_HEADER_LEN: usize = 4; // VER + REP + RSV + ATYP
+
+	// Step 1: Connect to the SOCKS5 proxy
+	let mut tcp_stream = TcpStream::connect(&tor_proxy_addr).await.map_err(|_| ())?;
+
+	// Step 2: Method selection — request username/password auth
+	let method_selection_request = [VERSION, NMETHODS, USERNAME_PASSWORD_AUTH];
+	tcp_stream.write_all(&method_selection_request).await.map_err(|_| ())?;
+
+	let mut method_selection_reply = [0u8; METHOD_SELECT_REPLY_LEN];
+	tcp_stream.read_exact(&mut method_selection_reply).await.map_err(|_| ())?;
+	if method_selection_reply != [VERSION, USERNAME_PASSWORD_AUTH] {
+		return Err(());
+	}
+
+	// Step 3: Authenticate with random password for Tor stream isolation
+	let password: [u8; PASSWORD_ENTROPY_LEN] = entropy_source.get_secure_random_bytes();
+	let mut username_password_request = [0u8; USERNAME_PASSWORD_REQUEST_LEN];
+	{
+		let mut stream = &mut username_password_request[..];
+		stream.write_all(&[USERNAME_PASSWORD_VERSION, USERNAME_LEN as u8]).unwrap();
+		stream.write_all(USERNAME).unwrap();
+		stream.write_all(&[PASSWORD_LEN as u8]).unwrap();
+		for byte in password {
+			write!(stream, "{:02x}", byte).unwrap();
+		}
+	}
+	tcp_stream.write_all(&username_password_request).await.map_err(|_| ())?;
+
+	let mut auth_reply = [0u8; USERNAME_PASSWORD_REPLY_LEN];
+	tcp_stream.read_exact(&mut auth_reply).await.map_err(|_| ())?;
+	if auth_reply[1] != SUCCESS {
+		return Err(());
+	}
+
+	// Step 4: Send CONNECT request for the target address
+	let mut socks5_request = [0u8; SOCKS5_REQUEST_MAX_LEN];
+	let request_len = {
+		let mut stream = &mut socks5_request[..];
+		stream.write_all(&[VERSION, CMD_CONNECT, RSV]).unwrap();
+
+		match &addr {
+			SocketAddress::OnionV3 { ed25519_pubkey, checksum, version, port } => {
+				// Encode as domain name (base32 .onion hostname)
+				// OnionV3 address = base32(pubkey[32] || checksum[2] || version[1]) + ".onion"
+				let mut raw = Vec::with_capacity(35);
+				raw.extend_from_slice(ed25519_pubkey);
+				raw.push((checksum >> 8) as u8);
+				raw.push(*checksum as u8);
+				raw.push(*version);
+				let encoded = base32_encode_lowercase(&raw);
+				let mut onion_host = encoded.into_bytes();
+				onion_host.extend_from_slice(b".onion");
+
+				stream.write_all(&[ATYP_DOMAINNAME, onion_host.len() as u8]).unwrap();
+				stream.write_all(&onion_host).unwrap();
+				stream.write_all(&port.to_be_bytes()).unwrap();
+			},
+			SocketAddress::TcpIpV4 { addr: ip, port } => {
+				stream.write_all(&[ATYP_IPV4]).unwrap();
+				stream.write_all(ip).unwrap();
+				stream.write_all(&port.to_be_bytes()).unwrap();
+			},
+			SocketAddress::TcpIpV6 { addr: ip, port } => {
+				stream.write_all(&[ATYP_IPV6]).unwrap();
+				stream.write_all(ip).unwrap();
+				stream.write_all(&port.to_be_bytes()).unwrap();
+			},
+			SocketAddress::Hostname { hostname, port } => {
+				let host_str = hostname.to_string();
+				let host_bytes = host_str.as_bytes();
+				stream.write_all(&[ATYP_DOMAINNAME, host_bytes.len() as u8]).unwrap();
+				stream.write_all(host_bytes).unwrap();
+				stream.write_all(&port.to_be_bytes()).unwrap();
+			},
+			_ => return Err(()),
+		}
+
+		SOCKS5_REQUEST_MAX_LEN - stream.len()
+	};
+
+	tcp_stream.write_all(&socks5_request[..request_len]).await.map_err(|_| ())?;
+
+	// Step 5: Read SOCKS5 reply
+	let mut reply_header = [0u8; SOCKS5_REPLY_HEADER_LEN];
+	tcp_stream.read_exact(&mut reply_header).await.map_err(|_| ())?;
+
+	if reply_header[1] != SUCCESS {
+		return Err(());
+	}
+
+	// Consume the bound address from the reply
+	let addr_len = match reply_header[3] {
+		ATYP_IPV4 => IPV4_ADDR_LEN + 2,
+		ATYP_IPV6 => IPV6_ADDR_LEN + 2,
+		ATYP_DOMAINNAME => {
+			let mut len_buf = [0u8; 1];
+			tcp_stream.read_exact(&mut len_buf).await.map_err(|_| ())?;
+			len_buf[0] as usize + 2
+		},
+		_ => return Err(()),
+	};
+	let mut addr_buf = vec![0u8; addr_len];
+	tcp_stream.read_exact(&mut addr_buf).await.map_err(|_| ())?;
+
+	Ok(tcp_stream)
+}
+
+/// RFC 4648 base32 encoding (lowercase, no padding) for onion v3 address derivation.
+fn base32_encode_lowercase(data: &[u8]) -> String {
+	const ALPHABET: &[u8] = b"abcdefghijklmnopqrstuvwxyz234567";
+	let mut result = String::with_capacity((data.len() * 8 + 4) / 5);
+	let mut buffer: u64 = 0;
+	let mut bits_left = 0;
+
+	for &byte in data {
+		buffer = (buffer << 8) | byte as u64;
+		bits_left += 8;
+		while bits_left >= 5 {
+			bits_left -= 5;
+			result.push(ALPHABET[((buffer >> bits_left) & 0x1f) as usize] as char);
+		}
+	}
+
+	if bits_left > 0 {
+		buffer <<= 5 - bits_left;
+		result.push(ALPHABET[(buffer & 0x1f) as usize] as char);
+	}
+
+	result
+}