feat(gateway): optional system-wide disable of inbound auth

Add a `gateway.auth_disabled` setting (default false — auth required) that,
when on, lets inbound MCP clients connect without a Bearer token. This makes
the upcoming one-click per-workspace install trivial: a client config needs
only the URL + `X-Mcpmux-Workspace` header, no OAuth/access-key dance.

The middleware is now lenient rather than all-or-nothing: a valid token is
always honored when present, so flipping the setting never breaks an
already-configured client. With auth disabled and no valid token, the
connection is accepted as an anonymous client on the default Space; routing
still prefers the workspace header → binding. The toggle lives in
GatewayState (seeded from settings at startup, flipped live by
set_gateway_auth_disabled so no restart is needed).

Claude-Session: https://claude.ai/code/session_01Baan9JmzR43uxxRUh7CAMF
Signed-off-by: Mohammod Al Amin Ashik <maa.ashik00@gmail.com>

Author: its-mash

apps/desktop/src-tauri/src/commands/gateway.rs

@@ -920,6 +920,23 @@ pub async fn start_gateway(
     let grant_service = server.grant_service();
     let session_roots = server.session_roots();
 
+    // Seed the system-wide inbound-auth toggle into the running gateway from
+    // persisted settings (default: auth required). Live changes go through
+    // `set_gateway_auth_disabled`.
+    {
+        let disabled = app_state
+            .settings_repository
+            .get(GATEWAY_AUTH_DISABLED_KEY)
+            .await
+            .ok()
+            .flatten()
+            .map(|v| v == "true")
+            .unwrap_or(false);
+        if disabled {
+            gw_state.write().await.set_auth_disabled(true);
+        }
+    }
+
     // Subscribe to OAuth completions BEFORE spawn so we don't miss early
     // events emitted during initial auto-connect.
     let oauth_completion_rx = pool_service.oauth_manager().subscribe();
@@ -1105,6 +1122,47 @@ pub async fn reset_gateway_port(app_state: State<'_, AppState>) -> Result<(), St
     Ok(())
 }
 
+/// App-settings key for the system-wide inbound-auth toggle. Stored as
+/// `"true"`/`"false"`; missing means auth is required (the secure default).
+pub const GATEWAY_AUTH_DISABLED_KEY: &str = "gateway.auth_disabled";
+
+/// Whether inbound MCP authentication is disabled — connections are accepted
+/// without an access key (localhost-only convenience). Default **false** (auth
+/// required).
+#[tauri::command]
+pub async fn get_gateway_auth_disabled(app_state: State<'_, AppState>) -> Result<bool, String> {
+    let stored = app_state
+        .settings_repository
+        .get(GATEWAY_AUTH_DISABLED_KEY)
+        .await
+        .map_err(|e| e.to_string())?;
+    Ok(stored.map(|v| v == "true").unwrap_or(false))
+}
+
+/// Enable/disable system-wide inbound auth. Persists the setting AND mirrors it
+/// into the running gateway so the change takes effect immediately (no
+/// restart). When the gateway isn't running it's a no-op beyond persistence —
+/// `start_gateway` seeds the value on launch.
+#[tauri::command]
+pub async fn set_gateway_auth_disabled(
+    disabled: bool,
+    app_state: State<'_, AppState>,
+    gateway_state: State<'_, Arc<RwLock<GatewayAppState>>>,
+) -> Result<bool, String> {
+    app_state
+        .settings_repository
+        .set(GATEWAY_AUTH_DISABLED_KEY, &disabled.to_string())
+        .await
+        .map_err(|e| e.to_string())?;
+
+    let state = gateway_state.read().await;
+    if let Some(ref gw) = state.gateway_state {
+        gw.write().await.set_auth_disabled(disabled);
+    }
+    info!("[Gateway] Inbound auth disabled set to {}", disabled);
+    Ok(disabled)
+}
+
 /// Which port source a startup attempt would use.
 ///
 /// Kept as a string-valued enum for clean JSON serialization to the UI.

apps/desktop/src-tauri/src/lib.rs

@@ -945,6 +945,8 @@ pub fn run() {
             commands::get_gateway_port_settings,
             commands::set_gateway_port,
             commands::reset_gateway_port,
+            commands::get_gateway_auth_disabled,
+            commands::set_gateway_auth_disabled,
             commands::probe_gateway_start,
             commands::take_pending_port_conflict,
             commands::start_gateway,

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

@@ -18,6 +18,12 @@ use crate::auth::validate_token;
 use crate::logging::TraceContext;
 use crate::server::ServiceContainer;
 
+/// Synthetic client identity used when system-wide inbound auth is disabled and
+/// a connection arrives without a (valid) Bearer token. Routing still prefers
+/// the `X-Mcpmux-Workspace` header → binding; this id only feeds the rootless
+/// `client_grants` fallback (which finds none) → Space default.
+const ANONYMOUS_CLIENT_ID: &str = "mcpmux-anonymous";
+
 /// OAuth middleware for MCP endpoints using rmcp
 ///
 /// Extracts Bearer token → Verifies JWT → Resolves space → Injects OAuthContext
@@ -38,75 +44,99 @@ pub async fn mcp_oauth_middleware(
         .map(|ctx| ctx.trace_id.clone())
         .unwrap_or_else(|| "??????".to_string());
 
-    // Extract Authorization header
+    // System-wide inbound auth can be disabled (localhost-only convenience):
+    // when off, a connection is accepted without a Bearer token and routed by
+    // the workspace header / default space. A valid token is still honored when
+    // present, so flipping the setting never breaks an already-configured
+    // client. Default is auth-required.
+    let require_auth = !services.gateway_state.read().await.auth_disabled();
+
     let auth_header = request
         .headers()
         .get("authorization")
-        .and_then(|v| v.to_str().ok());
-
-    let Some(auth_value) = auth_header else {
-        warn!(trace_id = %trace_id, "Missing Authorization header");
-        return unauthorized_response("Missing Authorization header");
-    };
-
-    // Extract Bearer token
-    let token = match auth_value.strip_prefix("Bearer ") {
-        Some(t) => t,
-        None => {
-            warn!(trace_id = %trace_id, "Authorization header must use Bearer scheme");
-            return unauthorized_response("Authorization header must use Bearer scheme");
+        .and_then(|v| v.to_str().ok())
+        .map(str::to_owned);
+    let token = auth_header
+        .as_deref()
+        .and_then(|v| v.strip_prefix("Bearer "));
+
+    // Verify the Bearer token whenever one is present.
+    let claims = match token {
+        Some(token) => {
+            let jwt_secret = {
+                let state = services.gateway_state.read().await;
+                state.get_jwt_secret().map(|s| s.to_vec())
+            };
+            match jwt_secret {
+                Some(secret) => validate_token(token, &secret),
+                None => {
+                    warn!(trace_id = %trace_id, "JWT secret not configured");
+                    None
+                }
+            }
         }
+        None => None,
     };
 
-    // Verify JWT and extract claims
-    let jwt_secret = {
-        let state = services.gateway_state.read().await;
-        match state.get_jwt_secret() {
-            Some(secret) => secret.to_vec(),
-            None => {
-                warn!(trace_id = %trace_id, "JWT secret not configured");
+    // Resolve (client_id, space_id) from the token, or — when auth is disabled
+    // — fall back to an anonymous identity on the default space.
+    let (client_id, space_id) = if let Some(claims) = claims {
+        match services
+            .space_resolver_service
+            .resolve_space_for_client(&claims.client_id)
+            .await
+        {
+            Ok(id) => (claims.client_id, id),
+            Err(e) => {
+                warn!(
+                    trace_id = %trace_id,
+                    client_id = %claims.client_id,
+                    "Failed to resolve space: {}", e
+                );
                 return (
                     StatusCode::INTERNAL_SERVER_ERROR,
-                    "Server not configured for authentication",
+                    format!("Failed to resolve space: {}", e),
                 )
                     .into_response();
             }
         }
-    };
-
-    let claims = match validate_token(token, &jwt_secret) {
-        Some(claims) => claims,
-        None => {
-            warn!(trace_id = %trace_id, "Token verification failed");
-            return unauthorized_response("Invalid token");
-        }
-    };
-
-    // Resolve space for this client
-    let space_id = match services
-        .space_resolver_service
-        .resolve_space_for_client(&claims.client_id)
-        .await
-    {
-        Ok(id) => id,
-        Err(e) => {
-            warn!(
-                trace_id = %trace_id,
-                client_id = %claims.client_id,
-                "Failed to resolve space: {}", e
-            );
-            return (
-                StatusCode::INTERNAL_SERVER_ERROR,
-                format!("Failed to resolve space: {}", e),
-            )
-                .into_response();
+    } else if require_auth {
+        // No valid token and auth is required → 401 with the specific reason.
+        let msg = match auth_header.as_deref() {
+            None => "Missing Authorization header",
+            Some(v) if !v.starts_with("Bearer ") => "Authorization header must use Bearer scheme",
+            _ => "Invalid token",
+        };
+        warn!(trace_id = %trace_id, "{}", msg);
+        return unauthorized_response(msg);
+    } else {
+        // Auth disabled → accept anonymously on the default space. Routing
+        // still prefers the workspace header (pinned below) → binding.
+        match services.dependencies.space_repo.get_default().await {
+            Ok(Some(space)) => (ANONYMOUS_CLIENT_ID.to_string(), space.id),
+            Ok(None) => {
+                warn!(trace_id = %trace_id, "Auth disabled but no default space configured");
+                return (
+                    StatusCode::INTERNAL_SERVER_ERROR,
+                    "No default space configured",
+                )
+                    .into_response();
+            }
+            Err(e) => {
+                warn!(trace_id = %trace_id, "Failed to resolve default space: {}", e);
+                return (
+                    StatusCode::INTERNAL_SERVER_ERROR,
+                    format!("Failed to resolve default space: {}", e),
+                )
+                    .into_response();
+            }
         }
     };
 
     // Inject OAuth context via custom headers (rmcp will preserve these)
     request.headers_mut().insert(
         "x-mcpmux-client-id",
-        claims.client_id.parse().expect("valid header value"),
+        client_id.parse().expect("valid header value"),
     );
     request.headers_mut().insert(
         "x-mcpmux-space-id",
@@ -152,7 +182,7 @@ pub async fn mcp_oauth_middleware(
                 // Log single consolidated entry line
                 info!(
                     trace_id = %trace_id,
-                    client = %&claims.client_id[..claims.client_id.len().min(12)],
+                    client = %&client_id[..client_id.len().min(12)],
                     space = %&space_id.to_string()[..8],
                     method = method.as_deref().unwrap_or("-"),
                     "→ MCP"
@@ -185,7 +215,7 @@ pub async fn mcp_oauth_middleware(
         warn!(
             trace_id = %trace_id,
             status = %status,
-            client = %claims.client_id,
+            client = %client_id,
             method = mcp_method.as_deref().unwrap_or("-"),
             "← MCP error"
         );

crates/mcpmux-gateway/src/server/state.rs

@@ -61,6 +61,11 @@ pub struct GatewayState {
     client_metadata_service: Option<Arc<ClientMetadataService>>,
     /// Unified event broadcaster (UI subscribes to receive all domain events)
     domain_event_tx: broadcast::Sender<DomainEvent>,
+    /// When true, inbound MCP connections are accepted WITHOUT a Bearer token
+    /// (localhost-only convenience). Default false (auth required). Seeded from
+    /// the `gateway.auth_disabled` app setting at startup and flipped live by
+    /// the desktop toggle. A valid token is still honored when present.
+    auth_disabled: bool,
 }
 
 impl GatewayState {
@@ -77,6 +82,7 @@ impl GatewayState {
             inbound_client_repository: None,
             client_metadata_service: None,
             domain_event_tx,
+            auth_disabled: false,
         }
     }
 
@@ -86,6 +92,24 @@ impl GatewayState {
         self.base_url = base_url;
     }
 
+    /// Whether inbound MCP auth is disabled — connections may be accepted
+    /// without a Bearer token. See [`Self::auth_disabled`] field docs.
+    pub fn auth_disabled(&self) -> bool {
+        self.auth_disabled
+    }
+
+    /// Enable/disable system-wide inbound auth. Called at startup (seed from
+    /// settings) and live from the desktop toggle.
+    pub fn set_auth_disabled(&mut self, disabled: bool) {
+        if self.auth_disabled != disabled {
+            info!(
+                "[State] Inbound auth {}",
+                if disabled { "DISABLED" } else { "enabled" }
+            );
+        }
+        self.auth_disabled = disabled;
+    }
+
     /// Subscribe to domain events (new unified channel)
     pub fn subscribe_domain_events(&self) -> broadcast::Receiver<DomainEvent> {
         self.domain_event_tx.subscribe()
@@ -265,3 +289,19 @@ impl Default for GatewayState {
         Self::new(domain_event_tx)
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn auth_disabled_defaults_off_and_toggles() {
+        let mut state = GatewayState::default();
+        // Secure default: auth is required (not disabled).
+        assert!(!state.auth_disabled());
+        state.set_auth_disabled(true);
+        assert!(state.auth_disabled());
+        state.set_auth_disabled(false);
+        assert!(!state.auth_disabled());
+    }
+}