feat(gateway): resolve bindings from X-Mcpmux-Machine-Id header

Parse the per-device machine header on each MCP request and use it as the
top-priority Tier 1 signal when present, so tunneled callers are not mistaken
for the gateway host. Add integration tests for header outranking and deny.

Signed-off-by: Joe Sangiorgio <jsangio1@gmail.com>

Author: crimsonsunset

crates/mcpmux-gateway/src/consumers/mcp_notifier.rs

@@ -936,7 +936,7 @@ impl MCPNotifier {
             }
             match self
                 .feature_set_resolver
-                .resolve(Some(&session_id), Some(&client_id))
+                .resolve(Some(&session_id), Some(&client_id), None)
                 .await
             {
                 Ok(resolved) if resolved.space_id == Some(space_id) => {

crates/mcpmux-gateway/src/mcp/context.rs

@@ -5,11 +5,15 @@ use http;
 use rmcp::{model::Extensions, service::RequestContext, RoleServer};
 use uuid::Uuid;
 
-/// OAuth claims extracted from JWT token
+/// OAuth claims extracted from JWT token, plus optional per-device machine identity.
 #[derive(Debug, Clone)]
 pub struct OAuthContext {
     pub client_id: String,
     pub space_id: Uuid,
+    /// Physical device identity from the client's `X-Mcpmux-Machine-Id` header.
+    /// Distinct from the gateway's `local_machine_id` when callers reach a shared
+    /// tunneled gateway from multiple machines.
+    pub request_machine_id: Option<Uuid>,
 }
 
 /// Extract OAuth context from extensions
@@ -46,9 +50,16 @@ pub fn extract_oauth_context(extensions: &Extensions) -> Result<OAuthContext> {
     let space_id =
         Uuid::parse_str(space_id_str).map_err(|e| anyhow!("Failed to parse space_id: {}", e))?;
 
+    let request_machine_id = parts
+        .headers
+        .get("x-mcpmux-machine-id")
+        .and_then(|v| v.to_str().ok())
+        .and_then(|s| Uuid::parse_str(s).ok());
+
     Ok(OAuthContext {
         client_id,
         space_id,
+        request_machine_id,
     })
 }
 

crates/mcpmux-gateway/src/mcp/handler.rs

@@ -101,9 +101,12 @@ impl McpMuxGatewayHandler {
         client_id: &str,
         session_id: Option<&str>,
         root_for_prompt: Option<&str>,
+        request_machine_id: Option<uuid::Uuid>,
     ) {
         let resolver = &services.feature_set_resolver;
-        match resolver.resolve(session_id, Some(client_id)).await {
+        match resolver
+            .resolve(session_id, Some(client_id), request_machine_id)
+            .await {
             Ok(resolved) => {
                 info!(
                     %client_id,
@@ -192,11 +195,12 @@ impl McpMuxGatewayHandler {
         &self,
         session_id: Option<&str>,
         client_id: &str,
+        request_machine_id: Option<uuid::Uuid>,
     ) -> Result<(uuid::Uuid, Vec<String>), McpError> {
         let resolved = self
             .services
             .authorization_service
-            .resolve(session_id, Some(client_id))
+            .resolve(session_id, Some(client_id), request_machine_id)
             .await
             .map_err(|e| McpError::internal_error(format!("Failed to resolve: {e}"), None))?;
         let space_id = resolved.space_id.ok_or_else(|| {
@@ -226,6 +230,7 @@ impl McpMuxGatewayHandler {
         peer: &rmcp::service::Peer<RoleServer>,
         session_id: Option<&str>,
         client_id: &str,
+        request_machine_id: Option<uuid::Uuid>,
     ) {
         let Some(sid) = session_id else { return };
         // Fast path: already have a definitive answer (Some(roots),
@@ -318,6 +323,7 @@ impl McpMuxGatewayHandler {
                         &client_id,
                         Some(&session_id),
                         root_for_prompt.as_deref(),
+                        request_machine_id,
                     )
                     .await;
                 });
@@ -532,6 +538,7 @@ impl ServerHandler for McpMuxGatewayHandler {
                 let notifier = self.notification_bridge.clone();
                 let client_id_str = oauth_ctx.client_id.clone();
                 let session_id_for_task = session_id.clone();
+                let request_machine_id = oauth_ctx.request_machine_id;
                 tokio::spawn(async move {
                     // Retry list_roots() on transport errors with bounded
                     // backoff. Without roots a roots-capable session is
@@ -620,6 +627,7 @@ impl ServerHandler for McpMuxGatewayHandler {
                         &client_id_str,
                         Some(&session_id_for_task),
                         root_for_prompt.as_deref(),
+                        request_machine_id,
                     )
                     .await;
                 });
@@ -632,6 +640,7 @@ impl ServerHandler for McpMuxGatewayHandler {
                     &oauth_ctx.client_id,
                     Some(&session_id),
                     None,
+                    oauth_ctx.request_machine_id,
                 )
                 .await;
             }
@@ -671,6 +680,7 @@ impl ServerHandler for McpMuxGatewayHandler {
         let notifier = self.notification_bridge.clone();
         let client_id_str = oauth_ctx.client_id.clone();
         let session_id_for_task = session_id.clone();
+        let request_machine_id = oauth_ctx.request_machine_id;
         tokio::spawn(async move {
             match peer.list_roots().await {
                 Ok(result) => {
@@ -702,6 +712,7 @@ impl ServerHandler for McpMuxGatewayHandler {
                         &client_id_str,
                         Some(&session_id_for_task),
                         root_for_prompt.as_deref(),
+                        request_machine_id,
                     )
                     .await;
                 }
@@ -734,13 +745,18 @@ impl ServerHandler for McpMuxGatewayHandler {
             &context.peer,
             session_id_owned.as_deref(),
             &oauth_ctx.client_id,
+            oauth_ctx.request_machine_id,
         )
         .await;
         // Resolve routing once: the resolver returns the authoritative
         // (Space, FS) for this session — this may differ from oauth_ctx
         // when a WorkspaceBinding redirects to another space.
         let (space_id, feature_set_ids) = self
-            .resolve_routing(session_id_owned.as_deref(), &oauth_ctx.client_id)
+            .resolve_routing(
+                session_id_owned.as_deref(),
+                &oauth_ctx.client_id,
+                oauth_ctx.request_machine_id,
+            )
             .await?;
 
         // Get advertised (surfaced) tools only — full invokable set is reachable
@@ -810,14 +826,14 @@ impl ServerHandler for McpMuxGatewayHandler {
         // connection). Without the probe it resolves to empty FS ids and
         // fails "not allowed by the current grants" — breaking the
         // list==call invariant the list handlers already uphold.
-        self.ensure_roots_probed(&context.peer, session_id, &oauth_ctx.client_id)
+        self.ensure_roots_probed(&context.peer, session_id, &oauth_ctx.client_id, oauth_ctx.request_machine_id)
             .await;
 
         // Resolve routing once — the binding's target space is authoritative
         // (may differ from oauth_ctx.space_id). Needed both to gate the
         // per-Space meta tools below and to route a normal tool call.
         let (space_id, feature_set_ids) = self
-            .resolve_routing(session_id, &oauth_ctx.client_id)
+            .resolve_routing(session_id, &oauth_ctx.client_id, oauth_ctx.request_machine_id)
             .await?;
 
         // Intercept meta tools (mcpmux_*) BEFORE feature-set filtering, gated
@@ -1032,10 +1048,15 @@ impl ServerHandler for McpMuxGatewayHandler {
             &context.peer,
             session_id_owned.as_deref(),
             &oauth_ctx.client_id,
+            oauth_ctx.request_machine_id,
         )
         .await;
         let (space_id, feature_set_ids) = self
-            .resolve_routing(session_id_owned.as_deref(), &oauth_ctx.client_id)
+            .resolve_routing(
+                session_id_owned.as_deref(),
+                &oauth_ctx.client_id,
+                oauth_ctx.request_machine_id,
+            )
             .await?;
 
         // Get advertised (surfaced) prompts only — full fetchable set is reachable
@@ -1086,10 +1107,15 @@ impl ServerHandler for McpMuxGatewayHandler {
             &context.peer,
             session_id_owned.as_deref(),
             &oauth_ctx.client_id,
+            oauth_ctx.request_machine_id,
         )
         .await;
         let (space_id, feature_set_ids) = self
-            .resolve_routing(session_id_owned.as_deref(), &oauth_ctx.client_id)
+            .resolve_routing(
+                session_id_owned.as_deref(),
+                &oauth_ctx.client_id,
+                oauth_ctx.request_machine_id,
+            )
             .await?;
 
         let (server_id, prompt_name) = self
@@ -1180,10 +1206,15 @@ impl ServerHandler for McpMuxGatewayHandler {
             &context.peer,
             session_id_owned.as_deref(),
             &oauth_ctx.client_id,
+            oauth_ctx.request_machine_id,
         )
         .await;
         let (space_id, feature_set_ids) = self
-            .resolve_routing(session_id_owned.as_deref(), &oauth_ctx.client_id)
+            .resolve_routing(
+                session_id_owned.as_deref(),
+                &oauth_ctx.client_id,
+                oauth_ctx.request_machine_id,
+            )
             .await?;
 
         // Get advertised (surfaced) resources only — full readable set is reachable
@@ -1232,10 +1263,15 @@ impl ServerHandler for McpMuxGatewayHandler {
             &context.peer,
             session_id_owned.as_deref(),
             &oauth_ctx.client_id,
+            oauth_ctx.request_machine_id,
         )
         .await;
         let (space_id, feature_set_ids) = self
-            .resolve_routing(session_id_owned.as_deref(), &oauth_ctx.client_id)
+            .resolve_routing(
+                session_id_owned.as_deref(),
+                &oauth_ctx.client_id,
+                oauth_ctx.request_machine_id,
+            )
             .await?;
 
         let authorized_resources = self

crates/mcpmux-gateway/src/services/authorization.rs

@@ -33,7 +33,10 @@ impl AuthorizationService {
         _space_id: &Uuid,
         session_id: Option<&str>,
     ) -> Result<Vec<String>> {
-        let resolved = self.resolver.resolve(session_id, Some(client_id)).await?;
+        let resolved = self
+            .resolver
+            .resolve(session_id, Some(client_id), None)
+            .await?;
         Ok(resolved.feature_set_ids)
     }
 
@@ -44,8 +47,11 @@ impl AuthorizationService {
         &self,
         session_id: Option<&str>,
         client_id: Option<&str>,
+        request_machine_id: Option<Uuid>,
     ) -> Result<ResolvedFeatureSet> {
-        self.resolver.resolve(session_id, client_id).await
+        self.resolver
+            .resolve(session_id, client_id, request_machine_id)
+            .await
     }
 
     /// Does this session/client resolve to any FeatureSet?

crates/mcpmux-gateway/src/services/feature_set_resolver.rs

@@ -30,8 +30,11 @@
 //!     return (default_space, [], Unbound)
 //! ```
 //!
-//! Signal 3 (machine) scopes binding lookup: client machine → local machine
-//! → global. A path bound only on another machine does not match here.
+//! Signal 3 (machine) scopes binding lookup. When the client sends
+//! `X-Mcpmux-Machine-Id`, only that machine and global bindings are
+//! considered — gateway `local_machine_id` and `inbound_clients.machine_id`
+//! are skipped so a tunneled caller is not mistaken for the gateway host.
+//! Without the header: client machine → local machine → global.
 //!
 //! ## Deny by default
 //!
@@ -225,13 +228,28 @@ impl FeatureSetResolverService {
         *self.local_machine_id.write().await = id;
     }
 
-    /// Tier 1 exact binding lookup: client machine, then local machine, then global.
+    /// Tier 1 exact binding lookup: request machine header, then client machine,
+    /// then local machine, then global.
     async fn find_binding_for_roots(
         &self,
         roots: &[String],
         client_id: Option<&str>,
+        request_machine_id: Option<Uuid>,
     ) -> Result<Option<mcpmux_core::WorkspaceBinding>> {
         for root in roots {
+            if let Some(header_machine) = request_machine_id {
+                if let Some(binding) = self
+                    .binding_repo
+                    .find_exact_for_machine(&header_machine, root, client_id)
+                    .await?
+                {
+                    return Ok(Some(binding));
+                }
+                if let Some(binding) = self.binding_repo.find_exact_global(root).await? {
+                    return Ok(Some(binding));
+                }
+                continue;
+            }
             if let Some(cid) = client_id {
                 if let Some(client_machine) = self.client_repo.get_machine_id(cid).await? {
                     if let Some(binding) = self
@@ -324,10 +342,13 @@ impl FeatureSetResolverService {
     /// the caller is stateless — e.g. desktop UI HTTP path).
     /// `client_id`: the OAuth client identity. Used only for the Tier-2
     /// `client_grants` lookup; ignored for binding-based routing.
+    /// `request_machine_id`: optional per-device identity from
+    /// `X-Mcpmux-Machine-Id`; highest-priority machine signal for Tier 1.
     pub async fn resolve(
         &self,
         session_id: Option<&str>,
         client_id: Option<&str>,
+        request_machine_id: Option<Uuid>,
     ) -> Result<ResolvedFeatureSet> {
         let default_space_id = match self.space_repo.get_default().await? {
             Some(s) => s.id,
@@ -376,7 +397,7 @@ impl FeatureSetResolverService {
             if has_roots {
                 let reported_roots = roots.expect("has_roots implies Some");
                 if let Some(binding) = self
-                    .find_binding_for_roots(&reported_roots, client_id)
+                    .find_binding_for_roots(&reported_roots, client_id, request_machine_id)
                     .await?
                 {
                     debug!(

crates/mcpmux-gateway/src/services/meta_tools/meta_tool_common.rs

@@ -58,7 +58,7 @@ pub(crate) async fn caller_space_id(call: &MetaToolCall<'_>) -> Result<Uuid, Met
     let resolved = call
         .ctx
         .resolver
-        .resolve(call.session_id, Some(call.client_id))
+        .resolve(call.session_id, Some(call.client_id), None)
         .await?;
     if let Some(space_id) = resolved.space_id {
         return Ok(space_id);
@@ -76,7 +76,7 @@ pub(crate) async fn caller_resolution(
 ) -> Result<ResolvedFeatureSet, MetaToolError> {
     call.ctx
         .resolver
-        .resolve(call.session_id, Some(call.client_id))
+        .resolve(call.session_id, Some(call.client_id), None)
         .await
         .map_err(|e| MetaToolError::Internal(e.to_string()))
 }

crates/mcpmux-gateway/src/services/meta_tools/set_workspace_root.rs

@@ -77,7 +77,7 @@ impl MetaTool for SetWorkspaceRootTool {
         let resolved = call
             .ctx
             .resolver
-            .resolve(Some(session_id), Some(call.client_id))
+            .resolve(Some(session_id), Some(call.client_id), None)
             .await?;
 
         let space_id = resolved

tests/rust/tests/integration/effective_features.rs

@@ -152,7 +152,7 @@ impl Ctx {
     /// The tools a session actually sees — the exact two-step the request
     /// handler runs: resolve the mapping, then pull its FS-filtered tools.
     async fn effective_tools(&self, session_id: &str) -> Vec<String> {
-        let resolved = self.resolver.resolve(Some(session_id), None).await.unwrap();
+        let resolved = self.resolver.resolve(Some(session_id), None, None).await.unwrap();
         let tools = self
             .feature_service
             .get_tools_for_grants(&self.space_id_str, &resolved.feature_set_ids)
@@ -263,7 +263,7 @@ async fn empty_mapping_yields_zero_effective_tools() {
     ctx.session_roots.set("sess", [root]);
     ctx.session_roots.set_roots_capable("sess", true);
 
-    let resolved = ctx.resolver.resolve(Some("sess"), None).await.unwrap();
+    let resolved = ctx.resolver.resolve(Some("sess"), None, None).await.unwrap();
     assert_eq!(resolved.source, ResolutionSource::WorkspaceBinding);
     assert!(resolved.feature_set_ids.is_empty());
     assert!(ctx.effective_tools("sess").await.is_empty());
@@ -296,7 +296,7 @@ async fn unbound_session_returns_no_tools() {
     ctx.session_roots.set("sess", [root]);
     ctx.session_roots.set_roots_capable("sess", true);
 
-    let resolved = ctx.resolver.resolve(Some("sess"), None).await.unwrap();
+    let resolved = ctx.resolver.resolve(Some("sess"), None, None).await.unwrap();
     assert_eq!(resolved.source, ResolutionSource::Unbound);
     assert!(resolved.feature_set_ids.is_empty());
     assert!(ctx.effective_tools("sess").await.is_empty());
@@ -332,7 +332,7 @@ async fn empty_starter_grants_nothing_to_unbound_session() {
     ctx.session_roots.set("sess", [root]);
     ctx.session_roots.set_roots_capable("sess", true);
 
-    let resolved = ctx.resolver.resolve(Some("sess"), None).await.unwrap();
+    let resolved = ctx.resolver.resolve(Some("sess"), None, None).await.unwrap();
     assert_eq!(resolved.source, ResolutionSource::Unbound);
     assert!(resolved.feature_set_ids.is_empty());
     assert!(ctx.effective_tools("sess").await.is_empty());