feat(mcp): allow a hosted MCP server on a literal loopback IP

crates/extensions/ironclaw_extension_host/src/capability_surface.rs

@@ -198,9 +198,18 @@ pub fn extension_network_policy(capability: &ActiveExtensionCapability) -> Netwo
     // declares the `network` effect but no targets is still caught by the
     // effect-based obligation gate and fails as misconfigured.)
     let has_egress_targets = !targets.is_empty();
+    // A capability whose every target is a literal loopback IP is exempt from
+    // the private-range denial — the same on-device boundary the hosted-MCP
+    // egress plan holds. Keeping the deny here would allowlist the loopback
+    // host and then refuse it anyway. `localhost` and non-loopback literals
+    // are not loopback patterns, so they keep the guard.
+    let all_targets_loopback = has_egress_targets
+        && targets.iter().all(|target| {
+            crate::hosted_mcp_admission::is_loopback_host_pattern(&target.host_pattern)
+        });
     NetworkPolicy {
         allowed_targets: targets,
-        deny_private_ip_ranges: has_egress_targets,
+        deny_private_ip_ranges: has_egress_targets && !all_targets_loopback,
         max_egress_bytes: capability.max_egress_bytes.filter(|_| has_egress_targets),
     }
 }
@@ -426,6 +435,54 @@ mod tests {
         assert_eq!(policy.max_egress_bytes, None);
     }
 
+    #[test]
+    fn loopback_only_targets_waive_the_private_range_denial() {
+        // A hosted MCP on a literal loopback IP: allowlisting the host and then
+        // denying private ranges would refuse the very target we just allowed.
+        // Same on-device boundary the hosted-MCP egress plan holds.
+        let loopback = NetworkTargetPattern {
+            scheme: Some(NetworkScheme::Https),
+            host_pattern: "127.0.0.1".to_string(),
+            port: Some(5443),
+        };
+        let capability = ActiveExtensionCapability {
+            id: CapabilityId::new("mcp-pantry.search_pantry").unwrap(),
+            provider: ExtensionId::new("mcp-pantry").unwrap(),
+            effects: vec![EffectKind::DispatchCapability, EffectKind::Network],
+            default_permission: PermissionMode::Allow,
+            runtime_credentials: Vec::new(),
+            network_targets: vec![loopback.clone()],
+            max_egress_bytes: None,
+            owner: ironclaw_extension_registry::InstallationOwner::Tenant,
+        };
+
+        let policy = extension_network_policy(&capability);
+
+        assert_eq!(policy.allowed_targets, vec![loopback.clone()]);
+        assert!(
+            !policy.deny_private_ip_ranges,
+            "a loopback-only allowlist waives the private-range guard"
+        );
+        assert!(
+            !policy.allowed_targets.is_empty(),
+            "the policy stays constrained by its allowlist, so the obligation is still emitted"
+        );
+
+        // One non-loopback target anywhere in the set re-arms the guard, and a
+        // DNS name that merely resolves to loopback never qualifies.
+        for other in [https("news.ycombinator.com"), https("localhost")] {
+            let mixed = ActiveExtensionCapability {
+                network_targets: vec![loopback.clone(), other.clone()],
+                ..capability.clone()
+            };
+            assert!(
+                extension_network_policy(&mixed).deny_private_ip_ranges,
+                "a non-loopback target ({}) must keep the SSRF guard",
+                other.host_pattern
+            );
+        }
+    }
+
     #[test]
     fn manifest_network_target_deduplicates_matching_credential_audience() {
         // A host declared in `network_targets` that also appears as a credential

crates/extensions/ironclaw_extension_host/src/hosted_mcp_admission.rs

@@ -16,23 +16,27 @@ impl CanonicalHostedMcpEndpoint {
     pub fn parse(input: &HostedMcpEndpoint) -> Result<Self, HostedMcpAdmissionError> {
         let url = url::Url::parse(input.as_str())
             .map_err(|_| HostedMcpAdmissionError::InvalidEndpoint)?;
-        if url.scheme() != "https"
-            || url.host_str().is_none()
+        let host = url.host().ok_or(HostedMcpAdmissionError::InvalidEndpoint)?;
+        // A literal loopback IP (127.0.0.0/8 or ::1) is a safe, non-rebindable
+        // on-device target: it is the single case where `http` is admitted and
+        // where an IP literal is allowed. Every other endpoint must be a public
+        // `https` URL, exactly as before.
+        let loopback_literal = is_loopback_ip_literal(&host);
+        let scheme_ok = url.scheme() == "https" || (url.scheme() == "http" && loopback_literal);
+        if !scheme_ok
             || !url.username().is_empty()
             || url.password().is_some()
             || url.fragment().is_some()
         {
             return Err(HostedMcpAdmissionError::InvalidEndpoint);
         }
-        let host = url
+        let host_str = url
             .host_str()
             .ok_or(HostedMcpAdmissionError::InvalidEndpoint)?;
-        if host.eq_ignore_ascii_case("localhost")
-            || matches!(
-                url.host(),
-                Some(url::Host::Ipv4(_)) | Some(url::Host::Ipv6(_))
-            )
-        {
+        // `localhost` (a DNS name a resolver could rebind) stays rejected; IP
+        // literals stay rejected unless they are a literal loopback address.
+        let is_ip_literal = matches!(host, url::Host::Ipv4(_) | url::Host::Ipv6(_));
+        if host_str.eq_ignore_ascii_case("localhost") || (is_ip_literal && !loopback_literal) {
             return Err(HostedMcpAdmissionError::InvalidEndpoint);
         }
         // Denylist, not allowlist: query parameters are load-bearing identity
@@ -81,6 +85,31 @@ impl CanonicalHostedMcpEndpoint {
     }
 }
 
+/// A literal IPv4/IPv6 loopback address (`127.0.0.0/8` or `::1`). Hostnames
+/// such as `localhost` are intentionally excluded: only a literal loopback IP
+/// is exempted, so no DNS name can later rebind to a non-loopback address.
+/// Shared by the admission gate above and the hosted-MCP egress planner in
+/// [`crate::mcp`] so the two agree on exactly what "loopback" means.
+pub(crate) fn is_loopback_ip_literal(host: &url::Host<&str>) -> bool {
+    match host {
+        url::Host::Ipv4(ip) => ip.is_loopback(),
+        url::Host::Ipv6(ip) => ip.is_loopback(),
+        url::Host::Domain(_) => false,
+    }
+}
+
+/// [`is_loopback_ip_literal`] for a stored `NetworkTargetPattern` host, which
+/// is a bare string rather than a parsed URL host. IPv6 patterns may or may not
+/// carry the URL bracket form, so both are accepted. A wildcard or DNS pattern
+/// never parses as an IP and is therefore never loopback.
+pub(crate) fn is_loopback_host_pattern(host_pattern: &str) -> bool {
+    host_pattern
+        .trim_start_matches('[')
+        .trim_end_matches(']')
+        .parse::<std::net::IpAddr>()
+        .is_ok_and(|ip| ip.is_loopback())
+}
+
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum HostedMcpAdmissionError {
     InvalidEndpoint,
@@ -108,11 +137,14 @@ mod tests {
     fn canonical_endpoint_rejects_credential_and_private_literal_forms() {
         for endpoint in [
             "https://user@example.test",
-            "https://127.0.0.1/mcp",
             "http://mcp.example.test",
             "https://mcp.example.test/rpc?Access_Token=must-not-persist",
-            "https://[::1]/mcp",
+            // `localhost` is a DNS name, not a literal loopback IP: rejected.
+            "http://localhost/mcp",
+            "https://localhost/mcp",
+            // A non-loopback IP literal stays rejected.
             "https://[2001:db8::1]/mcp",
+            "https://192.168.1.10/mcp",
             "https://mcp.example.test/rpc?client_secret=must-not-persist",
             "https://mcp.example.test/rpc?Password=must-not-persist",
             "https://mcp.example.test/rpc?signature=must-not-persist",
@@ -126,6 +158,26 @@ mod tests {
         }
     }
 
+    #[test]
+    fn canonical_endpoint_admits_literal_loopback_over_http_or_https() {
+        // A literal loopback IP is a safe on-device target: `http` is admitted
+        // and the IP literal is allowed, with the scheme/port preserved.
+        for endpoint in [
+            "http://127.0.0.1:5001/mcp",
+            "https://127.0.0.1/mcp",
+            "http://[::1]:5001/mcp",
+            "https://[::1]/mcp",
+        ] {
+            let input = HostedMcpEndpoint::new(endpoint).expect("wire endpoint");
+            CanonicalHostedMcpEndpoint::parse(&input)
+                .unwrap_or_else(|_| panic!("loopback endpoint should be admitted: {endpoint}"));
+        }
+
+        let input = HostedMcpEndpoint::new("http://127.0.0.1:5001/mcp").expect("wire endpoint");
+        let endpoint = CanonicalHostedMcpEndpoint::parse(&input).expect("canonical endpoint");
+        assert_eq!(endpoint.as_str(), "http://127.0.0.1:5001/mcp");
+    }
+
     #[test]
     fn canonical_endpoint_keeps_query_identity_and_normalizes_path() {
         let input = HostedMcpEndpoint::new("https://MCP.example.test/a/../rpc?b=2&a=1")