feat: tor managed services support

roshii · roshii · commit 7ed5cfffe47a · 2025-11-11T17:15:22.000+01:00
diff --git a/.python-version b/.python-version
@@ -0,0 +1 @@
+3.13
diff --git a/POWDefense-README.md b/POWDefense-README.md
@@ -0,0 +1,112 @@
+# POWDefense Configuration for JoinMarket Directory Nodes
+
+## Overview
+
+POWDefense (Proof-of-Work Defense) is an anti-DoS protection mechanism for Tor Onion Services, introduced in Tor 0.4.8.0. It helps protect onion services from denial-of-service attacks by requiring clients to solve computational puzzles before their connection requests are prioritized.
+
+**Important**: POWDefense is ONLY available for filesystem-based hidden services configured via `torrc`. It does NOT work with ephemeral services created via the ADD_ONION control port command.
+
+Reference: https://onionservices.torproject.org/technology/security/pow/#configuring-an-onion-service-with-the-pow-protection
+
+## Configuration
+
+### 1. Configure torrc
+
+Add these lines to your `torrc` file:
+
+```
+HiddenServiceDir /var/lib/hs/dn
+HiddenServicePort 5222 10.3.1.36:5222
+HiddenServicePoWDefensesEnabled 1
+HiddenServicePoWQueueRate 200
+HiddenServicePoWQueueBurst 1000
+```
+
+**Parameters explained:**
+- `HiddenServicePoWDefensesEnabled 1` - Enables POWDefense
+- `HiddenServicePoWQueueRate 200` - Maximum sustained rate of intro requests per second
+- `HiddenServicePoWQueueBurst 1000` - Maximum burst of intro requests allowed
+
+### 2. Configure directory-node.cfg
+
+Use the `tor-managed:` prefix in `hidden_service_dir` to signal that Tor (not JoinMarket) manages the hidden service:
+
+```ini
+[MESSAGING:onion]
+type = onion
+socks5_host = 10.3.1.87
+socks5_port = 8050
+tor_control_host = 10.3.1.87
+tor_control_port = 9051
+onion_serving_host = 10.3.1.36
+onion_serving_port = 5222
+
+# Use 'tor-managed:' prefix for Tor-managed hidden services with POWDefense
+hidden_service_dir = tor-managed:/var/lib/hs/dn
+directory_nodes = 1234abcd.onion:5222
+regtest_count = 0,0
+```
+
+## How It Works
+
+When `hidden_service_dir` starts with `tor-managed:`:
+
+1. **No Control Port Connection for HS Creation**: JoinMarket does NOT connect to Tor's control port to create the hidden service via ADD_ONION. Instead, Tor manages the service based on `torrc` configuration.
+
+2. **Reads Hostname from Filesystem**: JoinMarket polls for the `hostname` file in the hidden service directory created by Tor.
+
+3. **Waits for Initialization**: Before starting the listener, JoinMarket waits until the message channel is fully initialized (i.e., `self.self_as_peer` exists) to avoid race conditions.
+
+4. **Starts Listening**: Once initialized, JoinMarket starts listening on the configured `onion_serving_host:onion_serving_port`.
+
+## Docker Configuration
+
+Ensure the hidden service directory is properly mounted and accessible:
+
+```yaml
+services:
+  tor:
+    volumes:
+      - tor:/var/lib/tor
+      - ${DN_DATA_MOUNTPOINT:-.data/directory-node}:/var/lib/hs/dn
+
+  dn:
+    volumes:
+      - ${DN_DATA_MOUNTPOINT:-.data/directory-node}:/var/lib/hs/dn
+    depends_on:
+      - tor
+```
+
+## Why Not Ephemeral Services?
+
+Ephemeral services (created via ADD_ONION) do NOT support POWDefense parameters. According to Tor documentation:
+
+- POWDefense is configured via `torrc` using `HiddenService*` directives
+- The control port ADD_ONION command does not support POWDefense flags
+- POWDefense requires filesystem-based services with persistent directories
+
+## Compatibility
+
+- **Requires**: Tor 0.4.8.0 or later
+- **Not compatible with**: Onionbalance (as of July 2025)
+- **Works with**: Filesystem-based hidden services only
+
+## Monitoring
+
+Enable Tor logs to monitor POWDefense activity:
+
+```
+Log notice file /var/log/tor/notices.log
+```
+
+The logs will show:
+- PoW puzzle solving by clients
+- Queue statistics
+- Attack mitigation events
+
+## References
+
+- [Tor POWDefense Documentation](https://onionservices.torproject.org/technology/security/pow/)
+- [Proposal 327: A First Take at PoW Over Introduction Circuits](https://spec.torproject.org/proposals/327-pow-over-intro.html)
+- [Tor Manual: HiddenService Options](https://www.torproject.org/docs/tor-manual.html.en)
+
diff --git a/src/jmbase/twisted_utils.py b/src/jmbase/twisted_utils.py
@@ -1,13 +1,17 @@
+import os
 
-from zope.interface import implementer
+import txtorcon
+from twisted.internet import defer, reactor, task
+from twisted.internet.endpoints import (
+    TCP4ClientEndpoint,
+    UNIXClientEndpoint,
+    serverFromString,
+)
 from twisted.internet.error import ReactorNotRunning
-from twisted.internet import reactor, defer
-from twisted.internet.endpoints import (TCP4ClientEndpoint,
-                        UNIXClientEndpoint, serverFromString)
 from twisted.web.client import Agent, BrowserLikePolicyForHTTPS
-import txtorcon
+from txtorcon import TorConfig, TorControlProtocol
 from txtorcon.web import tor_agent
-from txtorcon import TorControlProtocol, TorConfig
+from zope.interface import implementer
 
 _custom_stop_reactor_is_set = False
 custom_stop_reactor = None
@@ -174,44 +178,87 @@ def start_tor(self):
         """ This function executes the workflow
         of starting the hidden service and returning its hostname
         """
-        self.info_callback("Attempting to start onion service on port: {} "
-                           "...".format(self.virtual_port))
+        self.info_callback(
+            f"Attempting to start onion service on port: {self.virtual_port} ..."
+        )
+
+        # Check if using Tor-managed mode (via torrc, not control port)
+        if self.hidden_service_dir.startswith("tor-managed:"):
+            self.start_tor_managed_onion()
+            return
+
+        # Ephemeral or txtorcon-managed hidden service (via control port)
+        if str(self.tor_control_host).startswith("unix:"):
+            control_endpoint = UNIXClientEndpoint(reactor, self.tor_control_host[5:])
+        else:
+            control_endpoint = TCP4ClientEndpoint(
+                reactor, self.tor_control_host, self.tor_control_port
+            )
+        d = txtorcon.connect(reactor, control_endpoint)
+
         if self.hidden_service_dir == "":
-            if str(self.tor_control_host).startswith('unix:'):
-                control_endpoint = UNIXClientEndpoint(reactor,
-                                        self.tor_control_host[5:])
-            else:
-                control_endpoint = TCP4ClientEndpoint(reactor,
-                                self.tor_control_host, self.tor_control_port)
-            d = txtorcon.connect(reactor, control_endpoint)
+            # Ephemeral hidden service (no persistence)
             d.addCallback(self.create_onion_ep)
             d.addErrback(self.setup_failed)
-            # TODO: add errbacks to the next two calls in
-            # the chain:
             d.addCallback(self.onion_listen)
             d.addCallback(self.print_host)
         else:
-            ep = "onion:" + str(self.virtual_port) + ":localPort="
-            ep += str(self.serving_port)
-            # endpoints.TCPHiddenServiceEndpoint creates version 2 by
-            # default for backwards compat (err, txtorcon needs to update that ...)
-            ep += ":version=3"
-            ep += ":hiddenServiceDir="+self.hidden_service_dir
-            onion_endpoint = serverFromString(reactor, ep)
-            d = onion_endpoint.listen(self.proto_factory)
+            # txtorcon-managed filesystem hidden service
+            d.addCallback(self.create_filesystem_onion_ep)
+            d.addErrback(self.setup_failed)
             d.addCallback(self.print_host_filesystem)
 
-
     def setup_failed(self, arg):
         # Note that actions based on this failure are deferred to callers:
         self.error_callback("Setup failed: " + str(arg))
 
     def create_onion_ep(self, t):
         self.tor_connection = t
-        portmap_string = config_to_hs_ports(self.virtual_port,
-                                self.serving_host, self.serving_port)
+        portmap_string = config_to_hs_ports(
+            self.virtual_port, self.serving_host, self.serving_port
+        )
         return t.create_onion_service(
-            ports=[portmap_string], private_key=txtorcon.DISCARD)
+            ports=[portmap_string], private_key=txtorcon.DISCARD
+        )
+
+    def create_filesystem_onion_ep(self, t):
+        """Create a persistent hidden service using txtorcon's filesystem support.
+        Requires local Tor control port access.
+        """
+        self.tor_connection = t
+        ep = "onion:" + str(self.virtual_port) + ":localPort="
+        ep += str(self.serving_port)
+        ep += ":version=3"
+        ep += ":hiddenServiceDir=" + self.hidden_service_dir
+        onion_endpoint = serverFromString(reactor, ep)
+        return onion_endpoint.listen(self.proto_factory)
+
+    def start_tor_managed_onion(self):
+        """
+        For Tor-managed hidden services: read hostname, start listening.
+        No control port connection needed.
+        """
+        hs_dir = self.hidden_service_dir.removeprefix("tor-managed:")
+        hostname_file = os.path.join(hs_dir, "hostname")
+
+        def check_and_start():
+            if not os.path.exists(hostname_file):
+                return
+
+            try:
+                with open(hostname_file, "r") as f:
+                    hostname = f.read().strip()
+            except Exception as e:
+                self.error_callback(f"Failed to read {hostname_file}: {e}")
+                poll_loop.stop()
+                return
+
+            poll_loop.stop()
+            self.info_callback(f"Using Tor-managed hidden service: {hostname}")
+            self.onion_hostname_callback(hostname)
+
+        poll_loop = task.LoopingCall(check_and_start)
+        poll_loop.start(0.5)
 
     def onion_listen(self, onion):
         # 'onion' arg is the created EphemeralOnionService object;
diff --git a/src/jmdaemon/onionmc.py b/src/jmdaemon/onionmc.py
@@ -8,7 +8,7 @@
 from twisted.internet import reactor, task, protocol
 from twisted.protocols import basic
 from twisted.application.internet import ClientService
-from twisted.internet.endpoints import TCP4ClientEndpoint
+from twisted.internet.endpoints import serverFromString, TCP4ClientEndpoint
 from twisted.internet.address import IPv4Address, IPv6Address
 from txtorcon.socks import (TorSocksEndpoint, HostUnreachableError,
                             SocksError, GeneralServerFailureError)
@@ -697,9 +697,12 @@ def __init__(self,
                 # it'll fire the `setup_error_callback`.
                 self.hs.start_tor()
 
-                # This will serve as our unique identifier, indicating
-                # that we are ready to communicate (in both directions) over Tor.
-                self.onion_hostname = None
+                # For tor-managed services, the hostname is set synchronously by start_tor()
+                # For ephemeral services, we need to wait for the callback
+                if not self.hidden_service_dir.startswith("tor-managed:"):
+                    # This will serve as our unique identifier, indicating
+                    # that we are ready to communicate (in both directions) over Tor.
+                    self.onion_hostname = None
         else:
             # dummy 'hostname' to indicate we can start running immediately:
             self.onion_hostname = NOT_SERVING_ONION_HOSTNAME
@@ -884,7 +887,7 @@ def connect_to_directories(self) -> None:
         if self.genesis_node:
             # we are a directory and we have no directory peers;
             # just start.
-            self.on_welcome(self)
+            self._start_listener()
             return
         # the remaining code is only executed by non-directories:
         for p in self.peers:
@@ -901,6 +904,13 @@ def connect_to_directories(self) -> None:
             self.wait_for_directories)
         self.wait_for_directories_loop.start(2.0)
 
+    def _start_listener(self) -> None:
+        serverstring = f"tcp:{self.onion_serving_port}:interface={self.onion_serving_host}"
+        onion_endpoint = serverFromString(reactor, serverstring)
+        d = onion_endpoint.listen(self.proto_factory)
+        d.addCallback(self.on_welcome)
+        d.addErrback(lambda f: self.setup_error_callback(f"Listen failed: {f}"))
+
     def handshake_as_client(self, peer: OnionPeer) -> None:
         assert peer.status() == PEER_STATUS_CONNECTED
         if self.self_as_peer.directory:
@@ -1461,7 +1471,8 @@ def wait_for_directories(self) -> None:
         # Note that even if the preceding (max) 50 seconds failed to
         # connect all our configured dps, we will keep trying and they
         # can still be used.
-        if not self.on_welcome_sent:
+        # For genesis nodes, on_welcome is called after the listener starts
+        if not self.on_welcome_sent and not self.genesis_node:
             self.on_welcome(self)
             self.on_welcome_sent = True
             self.wait_for_directories_loop.stop()
diff --git a/test/jmbase/test_twisted_utils.py b/test/jmbase/test_twisted_utils.py
@@ -0,0 +1,65 @@
+from unittest.mock import Mock, patch
+
+import pytest
+
+from jmbase.twisted_utils import JMHiddenService
+
+
+def mock_hs(hidden_service_dir: str = "") -> JMHiddenService:
+    return JMHiddenService(
+        Mock(),
+        Mock(),
+        Mock(),
+        Mock(),
+        "127.0.0.1",
+        9051,
+        "127.0.0.1",
+        8080,
+        80,
+        None,
+        hidden_service_dir,
+    )
+
+
+class TestTorManagedHiddenService:
+    @pytest.mark.parametrize(
+        "hidden_service_dir,expect_managed,expect_connect",
+        [
+            ("tor-managed:/path/to/dir", True, False),
+            ("/normal/path", False, True),
+        ],
+    )
+    def test_hidden_service_dir_detection(
+        self, hidden_service_dir, expect_managed, expect_connect
+    ):
+        with (
+            patch.object(JMHiddenService, "start_tor_managed_onion") as mock_managed,
+            patch("jmbase.twisted_utils.txtorcon.connect") as mock_connect,
+        ):
+            hs = mock_hs(hidden_service_dir)
+
+            hs.start_tor()
+
+            if expect_managed:
+                mock_managed.assert_called_once()
+                mock_connect.assert_not_called()
+            else:
+                mock_managed.assert_not_called()
+                mock_connect.assert_called_once()
+
+    def test_ephemeral_service_creation(self):
+        with patch("jmbase.twisted_utils.txtorcon") as mock_txtorcon:
+            mock_t = Mock()
+            mock_t.create_onion_service.return_value = Mock()
+
+            hs = mock_hs()
+            hs.tor_connection = mock_t
+            hs.virtual_port = 80
+            hs.serving_host = "127.0.0.1"
+            hs.serving_port = 8080
+
+            hs.create_onion_ep(mock_t)
+
+            mock_t.create_onion_service.assert_called_once_with(
+                ports=["80 127.0.0.1:8080"], private_key=mock_txtorcon.DISCARD
+            )
diff --git a/test/jmdaemon/test_onionmc.py b/test/jmdaemon/test_onionmc.py
