Skip to content

directory_server.handshake_handler

directory_server.handshake_handler

Handshake protocol handler for peer authentication and validation.

Implements Single Responsibility Principle: only handles handshakes.

Classes

HandshakeError

Bases: Exception

Source code in directory_server/src/directory_server/handshake_handler.py
23
24
class HandshakeError(Exception):
    pass

HandshakeHandler

Source code in directory_server/src/directory_server/handshake_handler.py
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
class HandshakeHandler:
    def __init__(
        self, network: NetworkType, server_nick: str, motd: str, neutrino_compat: bool = False
    ):
        self.network = network
        self.server_nick = server_nick
        self.motd = motd
        self.neutrino_compat = neutrino_compat

    def process_handshake(self, handshake_data: str, peer_location: str) -> tuple[PeerInfo, dict]:
        try:
            hs = json.loads(handshake_data)

            app_name = hs.get("app-name")
            is_directory = hs.get("directory", False)
            proto_ver = hs.get("proto-ver")
            features = hs.get("features", {})
            # Debug: Log received features for troubleshooting feature propagation
            if features:
                logger.debug(f"Handshake features from {hs.get('nick', 'unknown')}: {features}")
            location_string = hs.get("location-string")
            nick = hs.get("nick")
            network_str = hs.get("network")

            if not all([app_name, proto_ver, nick, network_str]):
                raise HandshakeError("Missing required handshake fields")

            if app_name.lower() != "joinmarket":
                raise HandshakeError(f"Invalid app name: {app_name}")

            if is_directory:
                raise HandshakeError("Directory nodes not accepted as clients")

            if not (JM_VERSION_MIN <= proto_ver <= JM_VERSION):
                raise HandshakeError(
                    f"Protocol version {proto_ver} not in supported range [{JM_VERSION_MIN}, {JM_VERSION}]"
                )

            peer_network = self._parse_network(network_str)
            if peer_network != self.network:
                raise HandshakeError(f"Network mismatch: {network_str} != {self.network.value}")

            onion_address, port = self._parse_location(location_string)

            # Determine negotiated version (highest both support)
            negotiated_version = min(proto_ver, JM_VERSION)

            # Check if peer supports Neutrino-compatible UTXO metadata
            peer_neutrino_compat = peer_supports_neutrino_compat(hs)

            peer_info = PeerInfo(
                nick=nick,
                onion_address=onion_address,
                port=port,
                status=PeerStatus.CONNECTED,
                is_directory=False,
                network=peer_network,
                features=features,
                protocol_version=negotiated_version,
                neutrino_compat=peer_neutrino_compat,
            )

            # Build our feature set - always include peerlist_features
            server_features: set[str] = {FEATURE_PEERLIST_FEATURES}
            if self.neutrino_compat:
                server_features.add(FEATURE_NEUTRINO_COMPAT)
            feature_set = FeatureSet(features=server_features)

            response = create_handshake_response(
                nick=self.server_nick,
                network=self.network.value,
                accepted=True,
                motd=self.motd,
                features=feature_set,
            )

            logger.info(
                f"Handshake accepted: {nick} from {peer_network.value} "
                f"at {peer_info.location_string} "
                f"(v{negotiated_version}, neutrino={peer_neutrino_compat})"
            )

            return (peer_info, response)

        except (json.JSONDecodeError, KeyError, ValueError) as e:
            logger.warning(f"Invalid handshake: {e}")
            raise HandshakeError(f"Invalid handshake format: {e}") from e

    def _parse_network(self, network_str: str) -> NetworkType:
        try:
            return NetworkType(network_str.lower())
        except ValueError as e:
            raise HandshakeError(f"Invalid network: {network_str}") from e

    def _parse_location(self, location: str) -> tuple[str, int]:
        if location == NOT_SERVING_ONION_HOSTNAME:
            return (NOT_SERVING_ONION_HOSTNAME, -1)

        try:
            if not location or ":" not in location:
                logger.warning(f"Incomplete location string: {location}, defaulting to not serving")
                return (NOT_SERVING_ONION_HOSTNAME, -1)

            host, port_str = location.split(":")
            port = int(port_str)
            if port <= 0 or port > 65535:
                raise ValueError("Invalid port")
            return (host, port)
        except (ValueError, AttributeError) as e:
            logger.warning(f"Invalid location string: {location}, defaulting to not serving: {e}")
            return (NOT_SERVING_ONION_HOSTNAME, -1)

    def create_rejection_response(self, reason: str) -> dict:
        return create_handshake_response(
            nick=self.server_nick,
            network=self.network.value,
            accepted=False,
            motd=f"Rejected: {reason}",
        )
Attributes
motd = motd instance-attribute
network = network instance-attribute
neutrino_compat = neutrino_compat instance-attribute
server_nick = server_nick instance-attribute
Functions
__init__(network: NetworkType, server_nick: str, motd: str, neutrino_compat: bool = False)
Source code in directory_server/src/directory_server/handshake_handler.py
28
29
30
31
32
33
34
def __init__(
    self, network: NetworkType, server_nick: str, motd: str, neutrino_compat: bool = False
):
    self.network = network
    self.server_nick = server_nick
    self.motd = motd
    self.neutrino_compat = neutrino_compat
create_rejection_response(reason: str) -> dict
Source code in directory_server/src/directory_server/handshake_handler.py
139
140
141
142
143
144
145
def create_rejection_response(self, reason: str) -> dict:
    return create_handshake_response(
        nick=self.server_nick,
        network=self.network.value,
        accepted=False,
        motd=f"Rejected: {reason}",
    )
process_handshake(handshake_data: str, peer_location: str) -> tuple[PeerInfo, dict]
Source code in directory_server/src/directory_server/handshake_handler.py
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
def process_handshake(self, handshake_data: str, peer_location: str) -> tuple[PeerInfo, dict]:
    try:
        hs = json.loads(handshake_data)

        app_name = hs.get("app-name")
        is_directory = hs.get("directory", False)
        proto_ver = hs.get("proto-ver")
        features = hs.get("features", {})
        # Debug: Log received features for troubleshooting feature propagation
        if features:
            logger.debug(f"Handshake features from {hs.get('nick', 'unknown')}: {features}")
        location_string = hs.get("location-string")
        nick = hs.get("nick")
        network_str = hs.get("network")

        if not all([app_name, proto_ver, nick, network_str]):
            raise HandshakeError("Missing required handshake fields")

        if app_name.lower() != "joinmarket":
            raise HandshakeError(f"Invalid app name: {app_name}")

        if is_directory:
            raise HandshakeError("Directory nodes not accepted as clients")

        if not (JM_VERSION_MIN <= proto_ver <= JM_VERSION):
            raise HandshakeError(
                f"Protocol version {proto_ver} not in supported range [{JM_VERSION_MIN}, {JM_VERSION}]"
            )

        peer_network = self._parse_network(network_str)
        if peer_network != self.network:
            raise HandshakeError(f"Network mismatch: {network_str} != {self.network.value}")

        onion_address, port = self._parse_location(location_string)

        # Determine negotiated version (highest both support)
        negotiated_version = min(proto_ver, JM_VERSION)

        # Check if peer supports Neutrino-compatible UTXO metadata
        peer_neutrino_compat = peer_supports_neutrino_compat(hs)

        peer_info = PeerInfo(
            nick=nick,
            onion_address=onion_address,
            port=port,
            status=PeerStatus.CONNECTED,
            is_directory=False,
            network=peer_network,
            features=features,
            protocol_version=negotiated_version,
            neutrino_compat=peer_neutrino_compat,
        )

        # Build our feature set - always include peerlist_features
        server_features: set[str] = {FEATURE_PEERLIST_FEATURES}
        if self.neutrino_compat:
            server_features.add(FEATURE_NEUTRINO_COMPAT)
        feature_set = FeatureSet(features=server_features)

        response = create_handshake_response(
            nick=self.server_nick,
            network=self.network.value,
            accepted=True,
            motd=self.motd,
            features=feature_set,
        )

        logger.info(
            f"Handshake accepted: {nick} from {peer_network.value} "
            f"at {peer_info.location_string} "
            f"(v{negotiated_version}, neutrino={peer_neutrino_compat})"
        )

        return (peer_info, response)

    except (json.JSONDecodeError, KeyError, ValueError) as e:
        logger.warning(f"Invalid handshake: {e}")
        raise HandshakeError(f"Invalid handshake format: {e}") from e