librats 0.8.0 → 0.9.0

package/native-src/src/dht.cpp

@@ -28,17 +28,19 @@
 namespace librats {
 
 
-DhtClient::DhtClient(int port, const std::string& bind_address, const std::string& data_directory) 
-    : port_(port), bind_address_(bind_address), data_directory_(data_directory), 
-      socket_(INVALID_SOCKET_VALUE), running_(false) {
+DhtClient::DhtClient(int port, const std::string& bind_address, const std::string& data_directory,
+                     AddressFamily address_family)
+    : port_(port), bind_address_(bind_address), data_directory_(data_directory),
+      address_family_(address_family), socket_(INVALID_SOCKET_VALUE), running_(false) {
     node_id_ = generate_node_id();
     routing_table_.resize(NODE_ID_SIZE * 8);  // 160 buckets for 160-bit node IDs
-    
+
     if (data_directory_.empty()) {
         data_directory_ = ".";
     }
-    
+
     LOG_DHT_INFO("DHT client created with node ID: " << node_id_to_hex(node_id_) <<
+                 " family: " << (is_ipv6() ? "IPv6" : "IPv4") <<
                  (bind_address_.empty() ? "" : " bind address: " + bind_address_) <<
                  " data directory: " << data_directory_);
 }
@@ -61,20 +63,22 @@ bool DhtClient::start() {
         return false;
     }
     
-    socket_ = create_udp_socket(port_, bind_address_);
+    // Each family gets its own single-family socket. IPv6 uses V6ONLY so the two
+    // sockets can share the same port and never cross-deliver mapped addresses.
+    socket_ = create_udp_socket(port_, bind_address_, address_family_);
 	// Fallback to free port
     if (!is_valid_socket(socket_) && port_ > 0) {
         // Requested port is not available, try ephemeral port as fallback
         int original_port = port_;
         LOG_DHT_WARN("UDP port " << original_port << " is not available, falling back to ephemeral port");
-        socket_ = create_udp_socket(0, bind_address_);
+        socket_ = create_udp_socket(0, bind_address_, address_family_);
         if (is_valid_socket(socket_)) {
             port_ = get_bound_port(socket_);
             LOG_DHT_INFO("Fell back from port " << original_port << " to ephemeral port " << port_);
         }
     }
     if (!is_valid_socket(socket_)) {
-        LOG_DHT_ERROR("Failed to create dual-stack UDP socket on port " << port_);
+        LOG_DHT_ERROR("Failed to create " << (is_ipv6() ? "IPv6" : "IPv4") << " UDP socket on port " << port_);
         return false;
     }
     
@@ -378,10 +382,14 @@ size_t DhtClient::get_active_announces_count() const {
 }
 
 std::vector<Peer> DhtClient::get_default_bootstrap_nodes() {
+    // Hostnames are resolved to the instance's family at send time (A for IPv4, AAAA for
+    // IPv6). dht.libtorrent.org publishes an AAAA record, giving the IPv6 network a
+    // reliable bootstrap entry point.
     return {
         {"router.bittorrent.com", 6881},
         {"dht.transmissionbt.com", 6881},
         {"router.utorrent.com", 6881},
+        {"dht.libtorrent.org", 25401},
         {"dht.aelitis.com", 6881}
     };
 }
@@ -509,6 +517,14 @@ void DhtClient::handle_message(const std::vector<uint8_t>& data, const Peer& sen
 }
 
 void DhtClient::add_node(const DhtNode& node, bool confirmed, bool no_verify) {
+    // IPv4 and IPv6 are separate Kademlia networks (BEP 32). Reject any node whose
+    // address family does not match this instance to keep the routing table clean.
+    if (network_utils::is_valid_ipv6(node.peer.ip) != is_ipv6()) {
+        LOG_DHT_DEBUG("Ignoring " << (is_ipv6() ? "non-IPv6" : "non-IPv4") << " node "
+                      << node.peer.ip << ":" << node.peer.port << " (wrong family)");
+        return;
+    }
+
     std::lock_guard<std::mutex> ping_lock(pending_pings_mutex_);
     std::lock_guard<std::mutex> lock(routing_table_mutex_);
 
@@ -980,7 +996,14 @@ void DhtClient::handle_krpc_announce_peer(const KrpcMessage& message, const Peer
 
 void DhtClient::handle_krpc_response(const KrpcMessage& message, const Peer& sender) {
     LOG_DHT_DEBUG("Handling KRPC response from " << sender.ip << ":" << sender.port);
-    
+
+    // BEP 42: nodes echo our external address back in the top-level "ip" field. Responses
+    // here are always replies to queries we sent, so the source is a node we chose to contact;
+    // we still require a consensus of distinct responders before regenerating our node ID.
+    if (!message.external_ip.empty()) {
+        maybe_update_external_ip(message.external_ip, sender);
+    }
+
     // Check if this is a ping verification response before normal processing
     handle_ping_verification_response(message.transaction_id, message.response_id, sender);
     
@@ -1077,14 +1100,25 @@ void DhtClient::handle_krpc_error(const KrpcMessage& message, const Peer& sender
 
 // KRPC sending functions
 bool DhtClient::send_krpc_message(const KrpcMessage& message, const Peer& peer) {
-    auto data = KrpcProtocol::encode_message(message);
+    // BEP 42: stamp the requester's external address into every response we send so the
+    // remote node can derive an IP-based node ID. Only copy the message when needed.
+    const KrpcMessage* out = &message;
+    KrpcMessage stamped;
+    if (message.type == KrpcMessageType::Response && message.external_ip.empty()) {
+        stamped = message;
+        stamped.external_ip = peer.ip;
+        stamped.external_port = peer.port;
+        out = &stamped;
+    }
+
+    auto data = KrpcProtocol::encode_message(*out);
     if (data.empty()) {
         LOG_DHT_ERROR("Failed to encode KRPC message");
         return false;
     }
     
     LOG_DHT_DEBUG("Sending KRPC message (" << data.size() << " bytes) to " << peer.ip << ":" << peer.port);
-    int result = send_udp_data(socket_, data, peer.ip, peer.port);
+    int result = send_udp_data(socket_, data, peer.ip, peer.port, address_family_);
     
     if (result > 0) {
         LOG_DHT_DEBUG("Successfully sent KRPC message to " << peer.ip << ":" << peer.port);
@@ -1104,12 +1138,16 @@ void DhtClient::send_krpc_ping(const Peer& peer) {
 void DhtClient::send_krpc_find_node(const Peer& peer, const NodeId& target) {
     std::string transaction_id = KrpcProtocol::generate_transaction_id();
     auto message = KrpcProtocol::create_find_node_query(transaction_id, node_id_, target);
+    // BEP 32: ask only for nodes of our own family (separate Kademlia networks)
+    message.want.push_back(is_ipv6() ? "n6" : "n4");
     send_krpc_message(message, peer);
 }
 
 void DhtClient::send_krpc_get_peers(const Peer& peer, const InfoHash& info_hash) {
     std::string transaction_id = KrpcProtocol::generate_transaction_id();
     auto message = KrpcProtocol::create_get_peers_query(transaction_id, node_id_, info_hash);
+    // BEP 32: ask only for nodes of our own family (separate Kademlia networks)
+    message.want.push_back(is_ipv6() ? "n6" : "n4");
     send_krpc_message(message, peer);
 }
 
@@ -1152,14 +1190,218 @@ NodeId DhtClient::generate_node_id() {
     std::random_device rd;
     std::mt19937 gen(rd());
     std::uniform_int_distribution<> dis(0, 255);
-    
+
     for (size_t i = 0; i < NODE_ID_SIZE; ++i) {
         id[i] = dis(gen);
     }
-    
+
     return id;
 }
 
+// ============================================================================
+// BEP 42: deriving the node ID from the external IP address
+// ============================================================================
+namespace {
+
+// CRC-32C (Castagnoli) — the polynomial mandated by BEP 42. Standard parameters:
+// reflected, init 0xFFFFFFFF, final XOR 0xFFFFFFFF. Bytes are processed in array order,
+// matching the BEP 42 reference implementation and its published test vectors.
+uint32_t crc32c(const uint8_t* data, size_t len) {
+    uint32_t crc = 0xFFFFFFFFu;
+    for (size_t i = 0; i < len; ++i) {
+        crc ^= data[i];
+        for (int k = 0; k < 8; ++k) {
+            crc = (crc & 1u) ? (crc >> 1) ^ 0x82F63B78u : (crc >> 1);
+        }
+    }
+    return crc ^ 0xFFFFFFFFu;
+}
+
+// Mask the leading octets of an IP per BEP 42 (4 octets for IPv4, 8 for IPv6).
+// Returns the number of octets written to `out`, or 0 on a parse failure.
+int masked_octets(const std::string& ip, uint8_t out[8]) {
+    static const uint8_t v4_mask[4] = { 0x03, 0x0f, 0x3f, 0xff };
+    static const uint8_t v6_mask[8] = { 0x01, 0x03, 0x07, 0x0f, 0x1f, 0x3f, 0x7f, 0xff };
+
+    if (network_utils::is_valid_ipv6(ip)) {
+        struct in6_addr addr6;
+        if (inet_pton(AF_INET6, ip.c_str(), &addr6) != 1) return 0;
+        for (int i = 0; i < 8; ++i) out[i] = addr6.s6_addr[i] & v6_mask[i];
+        return 8;
+    }
+
+    struct in_addr addr;
+    if (inet_pton(AF_INET, ip.c_str(), &addr) != 1) return 0;
+    uint32_t h = ntohl(addr.s_addr);
+    uint8_t ipb[4] = {
+        static_cast<uint8_t>((h >> 24) & 0xff), static_cast<uint8_t>((h >> 16) & 0xff),
+        static_cast<uint8_t>((h >> 8) & 0xff),  static_cast<uint8_t>(h & 0xff)
+    };
+    for (int i = 0; i < 4; ++i) out[i] = ipb[i] & v4_mask[i];
+    return 4;
+}
+
+// Compute the 3 deterministic prefix bytes of a BEP 42 node ID for (ip, seed).
+// Only the high 5 bits of prefix[2] are deterministic (the low 3 bits are random in a real ID).
+bool bep42_prefix(const std::string& ip, uint8_t seed, uint8_t prefix[3]) {
+    uint8_t octets[8];
+    int num = masked_octets(ip, octets);
+    if (num == 0) return false;
+    octets[0] |= static_cast<uint8_t>((seed & 0x7) << 5);
+    uint32_t c = crc32c(octets, static_cast<size_t>(num));
+    prefix[0] = static_cast<uint8_t>((c >> 24) & 0xff);
+    prefix[1] = static_cast<uint8_t>((c >> 16) & 0xff);
+    prefix[2] = static_cast<uint8_t>((c >> 8) & 0xf8);
+    return true;
+}
+
+} // namespace
+
+bool DhtClient::is_public_address(const std::string& ip) {
+    if (ip.empty()) return false;
+
+    if (network_utils::is_valid_ipv6(ip)) {
+        struct in6_addr a;
+        if (inet_pton(AF_INET6, ip.c_str(), &a) != 1) return false;
+        const uint8_t* b = a.s6_addr;
+        bool all_zero = true;
+        for (int i = 0; i < 16; ++i) { if (b[i]) { all_zero = false; break; } }
+        if (all_zero) return false;                              // ::  (unspecified)
+        bool loopback = (b[15] == 1);
+        for (int i = 0; i < 15; ++i) { if (b[i]) { loopback = false; break; } }
+        if (loopback) return false;                              // ::1
+        if ((b[0] & 0xfe) == 0xfc) return false;                 // fc00::/7  unique local
+        if (b[0] == 0xfe && (b[1] & 0xc0) == 0x80) return false; // fe80::/10 link-local
+        if (b[0] == 0xff) return false;                          // ff00::/8  multicast
+        return true;
+    }
+
+    struct in_addr a;
+    if (inet_pton(AF_INET, ip.c_str(), &a) != 1) return false;
+    uint32_t h = ntohl(a.s_addr);
+    uint8_t o1 = static_cast<uint8_t>((h >> 24) & 0xff);
+    uint8_t o2 = static_cast<uint8_t>((h >> 16) & 0xff);
+    if (o1 == 0) return false;                                   // 0.0.0.0/8
+    if (o1 == 127) return false;                                 // loopback
+    if (o1 == 10) return false;                                  // 10.0.0.0/8
+    if (o1 == 172 && o2 >= 16 && o2 <= 31) return false;         // 172.16.0.0/12
+    if (o1 == 192 && o2 == 168) return false;                    // 192.168.0.0/16
+    if (o1 == 169 && o2 == 254) return false;                    // 169.254.0.0/16 link-local
+    if (o1 == 100 && o2 >= 64 && o2 <= 127) return false;        // 100.64.0.0/10 CGNAT
+    if (o1 >= 224) return false;                                 // multicast / reserved
+    return true;
+}
+
+bool DhtClient::generate_node_id_from_ip(const std::string& ip, NodeId& out, std::mt19937& gen) {
+    uint8_t prefix[3];
+    std::uniform_int_distribution<int> dis(0, 255);
+    uint8_t seed = static_cast<uint8_t>(dis(gen));
+    if (!bep42_prefix(ip, seed, prefix)) return false;
+
+    out[0] = prefix[0];
+    out[1] = prefix[1];
+    out[2] = static_cast<uint8_t>(prefix[2] | (dis(gen) & 0x7));  // low 3 bits are random
+    for (int i = 3; i < 19; ++i) out[i] = static_cast<uint8_t>(dis(gen));
+    out[19] = seed;
+    return true;
+}
+
+bool DhtClient::verify_node_id_for_ip(const NodeId& id, const std::string& ip) {
+    // Local/private addresses cannot be verified (their IDs would be "wrong" anyway).
+    if (!is_public_address(ip)) return true;
+    uint8_t prefix[3];
+    if (!bep42_prefix(ip, id[19], prefix)) return true;          // unparseable -> don't reject
+    return id[0] == prefix[0]
+        && id[1] == prefix[1]
+        && (id[2] & 0xf8) == prefix[2];
+}
+
+void DhtClient::rebuild_routing_table_unlocked() {
+    // node_id_ changed; every node's bucket index is now stale. Re-bucket all of them.
+    std::vector<DhtNode> all;
+    for (auto& bucket : routing_table_) {
+        for (auto& node : bucket) all.push_back(std::move(node));
+        bucket.clear();
+    }
+    for (auto& node : all) {
+        int bucket_index = get_bucket_index(node.id);
+        if (bucket_index < 0 || bucket_index >= static_cast<int>(routing_table_.size())) continue;
+        auto& bucket = routing_table_[bucket_index];
+        if (bucket.size() < K_BUCKET_SIZE) bucket.push_back(std::move(node));
+    }
+}
+
+void DhtClient::set_external_ip(const std::string& ip) {
+    // Only public addresses of this instance's family can derive a valid node ID.
+    if (!is_public_address(ip)) return;
+    if (network_utils::is_valid_ipv6(ip) != is_ipv6()) return;
+
+    {
+        std::lock_guard<std::mutex> ext_lock(external_ip_mutex_);
+        if (ip == external_address_) return;  // already using this address
+        external_address_ = ip;
+    }
+
+    std::lock_guard<std::mutex> lock(routing_table_mutex_);
+    // If our current ID already matches this IP, keep it (avoids needless churn).
+    if (verify_node_id_for_ip(node_id_, ip)) {
+        LOG_DHT_DEBUG("External IP " << ip << " already matches current node ID (BEP 42)");
+        return;
+    }
+
+    std::random_device rd;
+    std::mt19937 gen(rd());
+    NodeId new_id;
+    if (!generate_node_id_from_ip(ip, new_id, gen)) return;
+
+    NodeId old_id = node_id_;
+    node_id_ = new_id;
+    rebuild_routing_table_unlocked();
+    LOG_DHT_INFO("Regenerated DHT node ID from external IP " << ip << " (BEP 42): "
+                 << node_id_to_hex(old_id) << " -> " << node_id_to_hex(new_id));
+}
+
+std::string DhtClient::get_external_address() const {
+    std::lock_guard<std::mutex> lock(external_ip_mutex_);
+    return external_address_;
+}
+
+void DhtClient::maybe_update_external_ip(const std::string& reported_ip, const Peer& responder) {
+    // Only consider public addresses of our own family.
+    if (!is_public_address(reported_ip)) return;
+    if (network_utils::is_valid_ipv6(reported_ip) != is_ipv6()) return;
+
+    std::string winner;
+    {
+        std::lock_guard<std::mutex> lock(external_ip_mutex_);
+        if (reported_ip == external_address_) return;  // already adopted
+
+        // One vote per distinct responder so a single peer cannot force a change.
+        if (external_ip_voters_.size() >= MAX_EXTERNAL_IP_VOTERS) {
+            external_ip_voters_.clear();
+            external_ip_votes_.clear();
+        }
+        if (!external_ip_voters_.insert(responder.ip).second) return;  // this responder already voted
+
+        int votes = ++external_ip_votes_[reported_ip];
+        // A vote for an address other than our current one is genuinely interesting
+        // (startup ramp-up, or a possible address change), so surface it at INFO.
+        LOG_DHT_INFO("External IP vote from " << responder.ip << " -> " << reported_ip
+                     << " (" << votes << "/" << EXTERNAL_IP_VOTE_THRESHOLD << ")");
+        if (votes >= EXTERNAL_IP_VOTE_THRESHOLD) {
+            winner = reported_ip;
+            external_ip_votes_.clear();
+            external_ip_voters_.clear();
+        }
+    }
+
+    if (!winner.empty()) {
+        LOG_DHT_INFO("External IP consensus reached: " << winner
+                     << " (>= " << EXTERNAL_IP_VOTE_THRESHOLD << " responders agree)");
+        set_external_ip(winner);
+    }
+}
+
 NodeId DhtClient::xor_distance(const NodeId& a, const NodeId& b) {
     NodeId result;
     for (size_t i = 0; i < NODE_ID_SIZE; ++i) {
@@ -2243,8 +2485,10 @@ bool DhtClient::add_search_requests(PendingSearch& search, DeferredCallbacks& de
         LOG_DHT_DEBUG("Querying node " << node_id_to_hex(node.id) << " at " << node.peer.ip << ":" << node.peer.port);
         
         auto message = KrpcProtocol::create_get_peers_query(transaction_id, node_id_, search.info_hash);
+        // BEP 32: request peers/nodes of our own family only
+        message.want.push_back(is_ipv6() ? "n6" : "n4");
         send_krpc_message(message, node.peer);
-        
+
         queries_sent++;
     }
     
@@ -2574,12 +2818,29 @@ std::string node_id_to_hex(const NodeId& id) {
 }
 
 // Routing table persistence implementation
+std::string DhtClient::routing_table_file_path() const {
+    // IPv6 instance uses a distinct filename suffix so it doesn't collide with the
+    // IPv4 instance bound to the same port.
+    const char* suffix = is_ipv6() ? "_v6" : "";
+#ifdef TESTING
+    if (port_ == 0) {
+        std::ostringstream oss;
+        oss << "dht_routing_" << this << suffix << ".json";
+        return oss.str();
+    }
+    return "dht_routing_" + std::to_string(port_) + suffix + ".json";
+#else
+    return data_directory_ + "/dht_routing_" + std::to_string(port_) + suffix + ".json";
+#endif
+}
+
 bool DhtClient::save_routing_table() {
     std::lock_guard<std::mutex> lock(routing_table_mutex_);
-    
+
     try {
         nlohmann::json routing_data;
         routing_data["version"] = 1;
+        routing_data["family"] = is_ipv6() ? "ipv6" : "ipv4";
         routing_data["node_id"] = node_id_to_hex(node_id_);
         routing_data["saved_at"] = std::chrono::system_clock::now().time_since_epoch().count();
         
@@ -2609,21 +2870,10 @@ bool DhtClient::save_routing_table() {
         
         routing_data["nodes"] = nodes_array;
         routing_data["count"] = saved_count;
-        
+
         // Determine file path
-        std::string file_path;
-        #ifdef TESTING
-            if (port_ == 0) {
-                std::ostringstream oss;
-                oss << "dht_routing_" << this << ".json";
-                file_path = oss.str();
-            } else {
-                file_path = "dht_routing_" + std::to_string(port_) + ".json";
-            }
-        #else
-            file_path = data_directory_ + "/dht_routing_" + std::to_string(port_) + ".json";
-        #endif
-        
+        std::string file_path = routing_table_file_path();
+
         // Write to file
         std::ofstream file(file_path);
         if (!file.is_open()) {
@@ -2648,19 +2898,8 @@ bool DhtClient::load_routing_table() {
     
     try {
         // Determine file path
-        std::string file_path;
-        #ifdef TESTING
-            if (port_ == 0) {
-                std::ostringstream oss;
-                oss << "dht_routing_" << this << ".json";
-                file_path = oss.str();
-            } else {
-                file_path = "dht_routing_" + std::to_string(port_) + ".json";
-            }
-        #else
-            file_path = data_directory_ + "/dht_routing_" + std::to_string(port_) + ".json";
-        #endif
-        
+        std::string file_path = routing_table_file_path();
+
         // Check if file exists
         std::ifstream file(file_path);
         if (!file.is_open()) {
@@ -2694,7 +2933,12 @@ bool DhtClient::load_routing_table() {
                 std::string node_id_hex = node_data["id"];
                 std::string ip = node_data["ip"];
                 int port = node_data["port"];
-                
+
+                // Skip nodes that don't belong to this instance's family
+                if (network_utils::is_valid_ipv6(ip) != is_ipv6()) {
+                    continue;
+                }
+
                 NodeId node_id = hex_to_node_id(node_id_hex);
                 Peer peer(ip, port);
                 DhtNode node(node_id, peer);
@@ -3049,11 +3293,17 @@ void DhtClient::spider_walk() {
             pool_size = spider_nodes_.size();
         }
         
-        // If still empty, bootstrap
+        // If still empty, bootstrap (rate-limited to once per 30 seconds)
         if (pool_size == 0) {
-            LOG_DHT_DEBUG("Spider walk: routing table empty too, re-bootstrapping");
-            for (const auto& bootstrap : get_default_bootstrap_nodes()) {
-                send_krpc_find_node(bootstrap, node_id_);
+            auto now = std::chrono::steady_clock::now();
+            if (now - last_spider_bootstrap_ >= std::chrono::seconds(30)) {
+                last_spider_bootstrap_ = now;
+                LOG_DHT_DEBUG("Spider walk: routing table empty too, re-bootstrapping");
+                for (const auto& bootstrap : get_default_bootstrap_nodes()) {
+                    send_krpc_find_node(bootstrap, node_id_);
+                }
+            } else {
+                LOG_DHT_DEBUG("Spider walk: skipping re-bootstrap (rate limited, last was < 30s ago)");
             }
         }
     }

package/native-src/src/dht.h

@@ -13,6 +13,7 @@
 #include <atomic>
 #include <chrono>
 #include <memory>
+#include <random>
 #include <condition_variable>
 
 // Hash specialization for Peer and NodeId (must be defined before use in unordered_map/set)
@@ -165,8 +166,12 @@ public:
      * Constructor
      * @param port The UDP port to bind to (default: 6881)
      * @param bind_address The interface IP address to bind to (empty for all interfaces)
+     * @param data_directory Directory for routing-table persistence
+     * @param address_family Address family this node operates on. IPv4 and IPv6 form
+     *        separate Kademlia networks (BEP 32), so each family needs its own DhtClient.
      */
-    DhtClient(int port = DHT_PORT, const std::string& bind_address = "", const std::string& data_directory = "");
+    DhtClient(int port = DHT_PORT, const std::string& bind_address = "", const std::string& data_directory = "",
+              AddressFamily address_family = AddressFamily::IPv4);
     
     /**
      * Destructor
@@ -222,9 +227,33 @@ public:
     
     /**
      * Get our node ID
-     * @return The node ID
+     * @return The node ID (returned by value; the ID may be regenerated at runtime
+     *         when our external IP is learned, see set_external_ip)
      */
-    const NodeId& get_node_id() const { return node_id_; }
+    NodeId get_node_id() const { return node_id_; }
+
+    /**
+     * Set our external (public) IP address and regenerate the node ID from it per BEP 42.
+     * IPv4/IPv6 node IDs must be derived from the matching-family external address, so this
+     * is a no-op if the address family does not match this instance. Safe to call at runtime;
+     * the routing table is re-bucketed against the new ID. Non-public/invalid addresses are ignored.
+     * @param ip External IP address as seen by the network (e.g. from STUN or DHT "ip" voting)
+     */
+    void set_external_ip(const std::string& ip);
+
+    /**
+     * Get the external address currently used to derive our node ID ("" if none/random).
+     */
+    std::string get_external_address() const;
+
+    /**
+     * BEP 42 helpers (public for testing / explicit use).
+     * generate_node_id_from_ip: build an IP-derived node ID (random where BEP 42 allows).
+     * verify_node_id_for_ip: check whether a node ID is valid for the given source IP
+     *   (always true for non-public IPs, which cannot be verified).
+     */
+    static bool generate_node_id_from_ip(const std::string& ip, NodeId& out, std::mt19937& gen);
+    static bool verify_node_id_for_ip(const NodeId& id, const std::string& ip);
     
     /**
      * Get number of nodes in routing table
@@ -337,11 +366,26 @@ public:
 #endif // RATS_SEARCH_FEATURES
     
     /**
-     * Get default BitTorrent DHT bootstrap nodes
+     * Get default BitTorrent DHT bootstrap nodes.
+     * Hostnames are resolved per-family at send time, so the same list serves both
+     * IPv4 and IPv6 (nodes without an AAAA record are simply skipped on IPv6).
      * @return Vector of bootstrap nodes
      */
     static std::vector<Peer> get_default_bootstrap_nodes();
+
+    /**
+     * Address family this DHT node operates on.
+     */
+    AddressFamily address_family() const { return address_family_; }
+    bool is_ipv6() const { return address_family_ == AddressFamily::IPv6; }
     
+    /**
+     * Compute the routing-table persistence file path for this instance.
+     * Includes the address family so the IPv4 and IPv6 nodes (which may share a port)
+     * never overwrite each other's saved state.
+     */
+    std::string routing_table_file_path() const;
+
     /**
      * Save routing table to disk
      * @return true if successful, false otherwise
@@ -364,10 +408,23 @@ private:
     int port_;
     std::string bind_address_;
     std::string data_directory_;
-    NodeId node_id_;
+    AddressFamily address_family_;  // IPv4 or IPv6 (this node's Kademlia network)
+    NodeId node_id_;                // protected by routing_table_mutex_ for writes; lock-free reads are benign
     socket_t socket_;
     std::atomic<bool> running_;
-    
+
+    // BEP 42: external-IP-derived node ID.
+    // We learn our external address from the top-level "ip" field other nodes echo back in
+    // their responses, and vote across distinct responders before trusting it (so a single
+    // malicious node cannot poison our node ID). external_address_/voting are guarded by
+    // external_ip_mutex_, which is NEVER held while acquiring any other DHT mutex.
+    std::string external_address_;                          // IP currently used to derive node_id_ ("" = random)
+    std::unordered_map<std::string, int> external_ip_votes_;// reported external IP -> vote count
+    std::unordered_set<std::string> external_ip_voters_;    // responder IPs already counted (dedup)
+    mutable std::mutex external_ip_mutex_;                  // Lock order: independent (never nested with others)
+    static constexpr int EXTERNAL_IP_VOTE_THRESHOLD = 5;    // distinct responders that must agree
+    static constexpr size_t MAX_EXTERNAL_IP_VOTERS = 1000;  // cap voter set to bound memory
+
     // ============================================================================
     // MUTEX LOCK ORDER - CRITICAL: Always acquire mutexes in this order to avoid deadlocks
     // ============================================================================
@@ -507,6 +564,9 @@ private:
     // Used to decide whether to respond with neighbor_id (spider contact) or real node_id (organic DHT)
     std::unordered_set<std::string> spider_contacted_ips_;
     
+    // Rate-limit re-bootstrapping in spider_walk to avoid DDOSing bootstrap nodes
+    std::chrono::steady_clock::time_point last_spider_bootstrap_{};  // epoch = never bootstrapped
+    
     // Spider helper methods
     void add_spider_node(const DhtNode& node);
     void add_spider_nodes(const std::vector<DhtNode>& nodes);
@@ -549,6 +609,10 @@ private:
     int get_bucket_index(const NodeId& id);
     
     NodeId generate_node_id();
+    // BEP 42 internals
+    static bool is_public_address(const std::string& ip);
+    void rebuild_routing_table_unlocked();  // re-bucket all nodes after node_id_ changed (routing_table_mutex_ held)
+    void maybe_update_external_ip(const std::string& reported_ip, const Peer& responder);
     NodeId xor_distance(const NodeId& a, const NodeId& b);
     bool is_closer(const NodeId& a, const NodeId& b, const NodeId& target);