feat(routes): warn when manual route targets a CIDR not advertised by the peer

When a user adds a route pointing at a peer that advertises auto-managed
routes (from its handshake), but none of those routes cover the requested
CIDR, the route is silently accepted yet traffic will never reach its
destination.

This commit makes the gap visible across all interfaces:
- IPC layer logs a tracing::warn and returns the warning in OkResponse.warning
- REPL/CLI prints the warning to stderr after "OK"
- MCP tool appends it to the success text
- REST API includes it in the SuccessResponse.message field

If the peer has no auto-managed routes (e.g. explicit-mode peers that
don't advertise routes), no warning is issued.

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

Author: maxholman

crates/api/src/handlers.rs

@@ -392,11 +392,15 @@ pub async fn add_route(
 
     match resp {
         Ok(r) => match r.response {
-            Some(management_response::Response::Ok(_)) => (
+            Some(management_response::Response::Ok(ok)) => (
                 StatusCode::CREATED,
                 Json(SuccessResponse {
                     success: true,
-                    message: None,
+                    message: if ok.warning.is_empty() {
+                        None
+                    } else {
+                        Some(ok.warning)
+                    },
                 }),
             ),
             Some(management_response::Response::Error(e)) => (

crates/cli/src/output.rs

@@ -157,8 +157,11 @@ pub fn print_response(resp: &ManagementResponse) -> Result<(), CtlError> {
                 println!("Fingerprint: {}", l.fingerprint);
             }
         }
-        Some(management_response::Response::Ok(_)) => {
+        Some(management_response::Response::Ok(ok)) => {
             println!("OK");
+            if !ok.warning.is_empty() {
+                eprintln!("warning: {}", ok.warning);
+            }
         }
         Some(management_response::Response::Error(e)) => {
             return Err(CtlError::Daemon(e.message.clone()));

crates/core/src/control/handler.rs

@@ -430,15 +430,32 @@ impl crate::node_api::NodeApi for Handler {
         ))
     }
 
-    fn add_route(&self, cidr: crate::Cidr, peer: String) -> crate::node_api::Result<()> {
+    fn add_route(
+        &self,
+        cidr: crate::Cidr,
+        peer: String,
+    ) -> crate::node_api::Result<Option<String>> {
         // Resolve peer name by prefix (will error if not found or ambiguous)
         let peer_info = self.peers.find_by_prefix(&peer)?;
 
-        let (_, new_entry) = self.routes.add(cidr, peer_info.name);
+        let (_, new_entry) = self.routes.add(cidr, peer_info.name.clone());
         let _ = self
             .route_updates
             .send(super::routes::RouteUpdate::Add(new_entry));
-        Ok(())
+
+        // Warn if the peer advertises routes but none of them cover the new CIDR.
+        // If the peer has no auto-routes at all, it may not advertise routes at all
+        // (e.g. an explicit-mode peer), so silence the warning in that case.
+        let auto_routes = self.routes.auto_routes_for_peer(&peer_info.name);
+        if !auto_routes.is_empty() && !auto_routes.iter().any(|r| r.cidr.contains(&cidr)) {
+            let warning = format!(
+                "peer {} does not advertise a route covering {cidr}; traffic may not reach the destination",
+                peer_info.name,
+            );
+            return Ok(Some(warning));
+        }
+
+        Ok(None)
     }
 
     fn route_del(&self, cidr: &crate::Cidr) -> crate::node_api::Result<()> {

crates/core/src/control/routes.rs

@@ -144,6 +144,21 @@ impl RouteTable {
         removed
     }
 
+    /// List all auto-managed routes for a specific peer.
+    ///
+    /// Returns routes that were installed from the peer's handshake
+    /// advertisement. Used to check whether a manually added route is
+    /// covered by what the peer actually advertises.
+    #[must_use]
+    pub fn auto_routes_for_peer(&self, peer: &str) -> Vec<RouteEntry> {
+        self.routes
+            .load()
+            .values()
+            .filter(|entry| entry.peer == peer && entry.auto_managed)
+            .cloned()
+            .collect()
+    }
+
     /// Look up a route by CIDR.
     #[must_use]
     pub fn get(&self, cidr: &Cidr) -> Option<RouteEntry> {
@@ -258,4 +273,31 @@ mod tests {
         let removed = table.remove_by_peer("no-such-peer");
         assert!(removed.is_empty());
     }
+
+    #[test]
+    fn test_auto_routes_for_peer() {
+        let table = RouteTable::new();
+        let cidr_auto: Cidr = "10.99.1.0/24".parse().unwrap();
+        let cidr_manual: Cidr = "10.99.3.0/24".parse().unwrap();
+        let cidr_other: Cidr = "10.99.2.0/24".parse().unwrap();
+
+        table.add_auto(cidr_auto, "peer-1".into());
+        table.add(cidr_manual, "peer-1".into());
+        table.add_auto(cidr_other, "peer-2".into());
+
+        let peer1_auto = table.auto_routes_for_peer("peer-1");
+        assert_eq!(
+            peer1_auto.len(),
+            1,
+            "only auto routes for peer-1 should be returned"
+        );
+        assert_eq!(peer1_auto[0].cidr, cidr_auto);
+
+        let peer2_auto = table.auto_routes_for_peer("peer-2");
+        assert_eq!(peer2_auto.len(), 1);
+        assert_eq!(peer2_auto[0].cidr, cidr_other);
+
+        let no_auto = table.auto_routes_for_peer("unknown-peer");
+        assert!(no_auto.is_empty());
+    }
 }

crates/core/src/ipc.rs

@@ -356,7 +356,14 @@ fn dispatch_request(request: &ManagementRequest, api: &dyn NodeApi) -> Managemen
 
         Some(management_request::Request::RouteAdd(req)) => match req.cidr.parse() {
             Ok(cidr) => match api.add_route(cidr, req.peer.clone()) {
-                Ok(()) => management_response::Response::Ok(OkResponse {}),
+                Ok(warning) => {
+                    if let Some(ref msg) = warning {
+                        tracing::warn!("{msg}");
+                    }
+                    management_response::Response::Ok(OkResponse {
+                        warning: warning.unwrap_or_default(),
+                    })
+                }
                 Err(e) => error_response(&e),
             },
             Err(_) => management_response::Response::Error(ErrorResponse {
@@ -367,7 +374,9 @@ fn dispatch_request(request: &ManagementRequest, api: &dyn NodeApi) -> Managemen
 
         Some(management_request::Request::RouteDel(req)) => match req.cidr.parse() {
             Ok(cidr) => match api.route_del(&cidr) {
-                Ok(()) => management_response::Response::Ok(OkResponse {}),
+                Ok(()) => management_response::Response::Ok(OkResponse {
+                    warning: String::new(),
+                }),
                 Err(e) => error_response(&e),
             },
             Err(_) => management_response::Response::Error(ErrorResponse {
@@ -383,7 +392,9 @@ fn dispatch_request(request: &ManagementRequest, api: &dyn NodeApi) -> Managemen
                 api.peer_disconnect(req.peer.clone())
             };
             match result {
-                Ok(()) => management_response::Response::Ok(OkResponse {}),
+                Ok(()) => management_response::Response::Ok(OkResponse {
+                    warning: String::new(),
+                }),
                 Err(ref e) => error_response(e),
             }
         }
@@ -412,15 +423,19 @@ fn dispatch_request(request: &ManagementRequest, api: &dyn NodeApi) -> Managemen
         },
 
         Some(management_request::Request::Disconnect(_)) => match api.disconnect() {
-            Ok(()) => management_response::Response::Ok(OkResponse {}),
+            Ok(()) => management_response::Response::Ok(OkResponse {
+                warning: String::new(),
+            }),
             Err(e) => error_response(&e),
         },
 
         Some(management_request::Request::Shutdown(_)) => {
             // Shutdown is handled by the caller via DaemonHandle, not NodeApi.
             // Return Ok here — the daemon layer should intercept ShutdownRequest
             // before it reaches dispatch, or handle it after dispatch returns.
-            management_response::Response::Ok(OkResponse {})
+            management_response::Response::Ok(OkResponse {
+                warning: String::new(),
+            })
         }
 
         Some(management_request::Request::HintSet(req)) => {
@@ -431,13 +446,17 @@ fn dispatch_request(request: &ManagementRequest, api: &dyn NodeApi) -> Managemen
                 target: target.into(),
             };
             match api.hint_set(hint) {
-                Ok(()) => management_response::Response::Ok(OkResponse {}),
+                Ok(()) => management_response::Response::Ok(OkResponse {
+                    warning: String::new(),
+                }),
                 Err(e) => error_response(&e),
             }
         }
 
         Some(management_request::Request::HintSetAuto(_)) => match api.hint_set_auto() {
-            Ok(()) => management_response::Response::Ok(OkResponse {}),
+            Ok(()) => management_response::Response::Ok(OkResponse {
+                warning: String::new(),
+            }),
             Err(e) => error_response(&e),
         },
 

crates/core/src/node_api.rs

@@ -195,7 +195,11 @@ pub trait NodeApi: Send + Sync {
     ///
     /// Only supported on entry nodes. Returns error for exit/relay nodes.
     /// Peer must be directly connected.
-    fn add_route(&self, cidr: Cidr, peer: String) -> Result<()>;
+    ///
+    /// Returns `Ok(Some(warning))` when the route was added but the peer's
+    /// advertised routes do not cover the requested CIDR, meaning traffic
+    /// may be silently dropped. Returns `Ok(None)` on clean success.
+    fn add_route(&self, cidr: Cidr, peer: String) -> Result<Option<String>>;
 
     /// Delete a route by CIDR.
     ///

crates/core/src/types.rs

@@ -87,6 +87,44 @@ impl Cidr {
     pub fn prefix_len(&self) -> u8 {
         self.prefix_len
     }
+
+    /// Returns `true` if `other` is a subnet of (or equal to) `self`.
+    ///
+    /// Requires the same IP family. A CIDR contains another when the
+    /// other's prefix length is at least as long (i.e. it is more specific
+    /// or equal), and the other's network address falls within this network.
+    #[must_use]
+    pub fn contains(&self, other: &Cidr) -> bool {
+        match (self.addr, other.addr) {
+            (IpAddr::V4(self_v4), IpAddr::V4(other_v4)) => {
+                if other.prefix_len < self.prefix_len {
+                    return false;
+                }
+                let self_bits = u32::from(self_v4);
+                let other_bits = u32::from(other_v4);
+                if self.prefix_len == 0 {
+                    true
+                } else {
+                    let shift = 32u32.saturating_sub(u32::from(self.prefix_len));
+                    (self_bits >> shift) == (other_bits >> shift)
+                }
+            }
+            (IpAddr::V6(self_v6), IpAddr::V6(other_v6)) => {
+                if other.prefix_len < self.prefix_len {
+                    return false;
+                }
+                let self_bits = u128::from(self_v6);
+                let other_bits = u128::from(other_v6);
+                if self.prefix_len == 0 {
+                    true
+                } else {
+                    let shift = 128u32.saturating_sub(u32::from(self.prefix_len));
+                    (self_bits >> shift) == (other_bits >> shift)
+                }
+            }
+            _ => false, // mixed IP families never contain each other
+        }
+    }
 }
 
 impl FromStr for Cidr {
@@ -246,6 +284,72 @@ mod tests {
         assert_eq!(NodeRole::Exit.to_string(), "exit");
     }
 
+    #[test]
+    fn test_cidr_contains_ipv4() {
+        let wide: Cidr = "10.0.0.0/8".parse().unwrap();
+        let narrow: Cidr = "10.99.3.0/24".parse().unwrap();
+        let equal: Cidr = "10.0.0.0/8".parse().unwrap();
+        let unrelated: Cidr = "192.168.0.0/16".parse().unwrap();
+        let broader: Cidr = "10.0.0.0/4".parse().unwrap();
+        let host: Cidr = "10.99.3.42/32".parse().unwrap();
+
+        assert!(
+            wide.contains(&narrow),
+            "10.0.0.0/8 should contain 10.99.3.0/24"
+        );
+        assert!(wide.contains(&equal), "a CIDR should contain itself");
+        assert!(
+            !wide.contains(&unrelated),
+            "10.0.0.0/8 should not contain 192.168.0.0/16"
+        );
+        assert!(
+            !wide.contains(&broader),
+            "10.0.0.0/8 should not contain 10.0.0.0/4"
+        );
+        assert!(
+            wide.contains(&host),
+            "10.0.0.0/8 should contain a host address within it"
+        );
+        assert!(
+            !narrow.contains(&wide),
+            "subnet should not contain supernet"
+        );
+    }
+
+    #[test]
+    fn test_cidr_contains_default_route() {
+        let default_route: Cidr = "0.0.0.0/0".parse().unwrap();
+        let any: Cidr = "192.168.100.0/24".parse().unwrap();
+        assert!(
+            default_route.contains(&any),
+            "0.0.0.0/0 should contain any IPv4 CIDR"
+        );
+    }
+
+    #[test]
+    fn test_cidr_contains_ipv6() {
+        let wide: Cidr = "fd00::/8".parse().unwrap();
+        let narrow: Cidr = "fd00:1234::/32".parse().unwrap();
+        let unrelated: Cidr = "2001:db8::/32".parse().unwrap();
+
+        assert!(
+            wide.contains(&narrow),
+            "fd00::/8 should contain fd00:1234::/32"
+        );
+        assert!(
+            !wide.contains(&unrelated),
+            "fd00::/8 should not contain 2001:db8::/32"
+        );
+    }
+
+    #[test]
+    fn test_cidr_contains_mixed_families() {
+        let v4: Cidr = "10.0.0.0/8".parse().unwrap();
+        let v6: Cidr = "fd00::/8".parse().unwrap();
+        assert!(!v4.contains(&v6), "IPv4 CIDR should not contain IPv6 CIDR");
+        assert!(!v6.contains(&v4), "IPv6 CIDR should not contain IPv4 CIDR");
+    }
+
     #[test]
     fn test_cidr_equality_and_hash() {
         use std::collections::HashSet;

crates/mcp/src/convert.rs

@@ -89,7 +89,13 @@ pub fn format_response(resp: &ManagementResponse) -> Result<String, String> {
             }
             Ok(out)
         }
-        Some(management_response::Response::Ok(_)) => Ok("OK".to_string()),
+        Some(management_response::Response::Ok(ok)) => {
+            if ok.warning.is_empty() {
+                Ok("OK".to_string())
+            } else {
+                Ok(format!("OK\nwarning: {}", ok.warning))
+            }
+        }
         Some(management_response::Response::Error(e)) => Err(e.message.clone()),
         None => Err("empty response from daemon".to_string()),
     }

crates/wire/proto/management.proto

@@ -215,7 +215,9 @@ enum ErrorCode {
   ERROR_CODE_PEER_AMBIGUOUS = 9;
 }
 
-message OkResponse {}
+message OkResponse {
+  string warning = 1; // non-fatal advisory (e.g. route reachability warning); empty when none
+}
 
 message ConnectResponse {
   string peer_addr = 1;    // resolved peer address