feat(routing): Phase 3 — Space lock as narrowing filter

Autonomous decisions:
- ON DELETE SET NULL for locked_space_id FK — matches machine_id and other inbound_clients Space FK conventions
- Tier 0 filters binding/grant results post-lookup rather than adding repo-level space predicates — keeps existing tier lookup order intact while enforcing the lock boundary

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

Author: crimsonsunset

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

@@ -717,6 +717,7 @@ fn generate_api_key() -> (String, String, String) {
 pub async fn register_api_key_client(
     gateway_state: State<'_, Arc<RwLock<GatewayAppState>>>,
     name: String,
+    locked_space_id: Option<String>,
 ) -> Result<RegisteredApiKeyClient, String> {
     let app_state = gateway_state.read().await;
     let Some(ref gw_state) = app_state.gateway_state else {
@@ -763,6 +764,20 @@ pub async fn register_api_key_client(
         .await
         .map_err(|e| format!("Failed to create client: {}", e))?;
 
+    let locked_space = locked_space_id
+        .as_deref()
+        .map(str::trim)
+        .filter(|s| !s.is_empty())
+        .map(|s| {
+            uuid::Uuid::parse_str(s).map_err(|_| format!("Invalid locked_space_id: {s}"))
+        })
+        .transpose()?;
+    if let Some(space_id) = locked_space {
+        repo.set_locked_space(&client_id, Some(space_id))
+            .await
+            .map_err(|e| format!("Failed to set Space lock: {}", e))?;
+    }
+
     let (key_id, plaintext, key_prefix) = generate_api_key();
     repo.create_api_key(&key_id, &client_id, &plaintext, &key_prefix, None, None)
         .await
@@ -782,7 +797,7 @@ pub async fn register_api_key_client(
     Ok(RegisteredApiKeyClient {
         client_id,
         client_name: trimmed.to_string(),
-        locked_space_id: None,
+        locked_space_id: locked_space.map(|id| id.to_string()),
         api_key: plaintext,
         key_prefix,
     })
@@ -825,10 +840,16 @@ pub async fn create_client_api_key(
     .await
     .map_err(|e| format!("Failed to create API key: {}", e))?;
 
+    let locked_space_id = repo
+        .get_locked_space(&client_id)
+        .await
+        .map_err(|e| format!("Failed to read Space lock: {}", e))?
+        .map(|id| id.to_string());
+
     Ok(RegisteredApiKeyClient {
         client_id,
         client_name: client.client_name,
-        locked_space_id: None,
+        locked_space_id,
         api_key: plaintext,
         key_prefix,
     })

apps/desktop/src/features/clients/RegisterApiKeyClientModal.tsx

@@ -14,6 +14,7 @@ import { useState } from 'react';
 import { AlertTriangle, Check, Copy, KeyRound, Loader2, ShieldCheck, X } from 'lucide-react';
 import { Button, Card, CardContent, CardDescription, CardHeader, CardTitle } from '@mcpmux/ui';
 import { registerApiKeyClient, type RegisteredApiKeyClient } from '@/lib/api/gateway';
+import { useSpaces } from '@/stores';
 
 interface RegisterApiKeyClientModalProps {
   onClose: () => void;
@@ -28,7 +29,9 @@ export function RegisterApiKeyClientModal({
   onClose,
   onRegistered,
 }: RegisterApiKeyClientModalProps) {
+  const spaces = useSpaces();
   const [name, setName] = useState('');
+  const [lockedSpaceId, setLockedSpaceId] = useState('');
   const [isSubmitting, setIsSubmitting] = useState(false);
   const [error, setError] = useState<string | null>(null);
   const [result, setResult] = useState<RegisteredApiKeyClient | null>(null);
@@ -43,7 +46,10 @@ export function RegisterApiKeyClientModal({
     setIsSubmitting(true);
     setError(null);
     try {
-      const client = await registerApiKeyClient(trimmed);
+      const client = await registerApiKeyClient(
+        trimmed,
+        lockedSpaceId.trim() ? lockedSpaceId.trim() : null
+      );
       setResult(client);
     } catch (e) {
       setError(e instanceof Error ? e.message : String(e));
@@ -162,6 +168,34 @@ export function RegisterApiKeyClientModal({
                 />
               </div>
 
+              <div>
+                <label
+                  htmlFor="api-key-locked-space"
+                  className="mb-1.5 block text-sm font-medium"
+                >
+                  Lock to a Space
+                </label>
+                <select
+                  id="api-key-locked-space"
+                  data-testid="register-api-key-locked-space"
+                  value={lockedSpaceId}
+                  onChange={(e) => setLockedSpaceId(e.target.value)}
+                  className="w-full rounded-xl border border-[rgb(var(--border))] bg-[rgb(var(--surface))] px-3.5 py-2.5 text-sm transition-all focus:border-[rgb(var(--accent))] focus:outline-none focus:ring-2 focus:ring-[rgb(var(--accent))]/40"
+                >
+                  <option value="">No lock — resolve across all Spaces</option>
+                  {spaces.map((space) => (
+                    <option key={space.id} value={space.id}>
+                      {space.icon ? `${space.icon} ` : ''}
+                      {space.name}
+                    </option>
+                  ))}
+                </select>
+                <p className="mt-1.5 text-xs text-[rgb(var(--muted))]">
+                  Optional. When set, the client can only use bindings or grants inside this Space.
+                  It still needs an explicit mapping — lock alone grants no tools.
+                </p>
+              </div>
+
               <div className="flex items-start gap-3 rounded-xl border border-[rgb(var(--border-subtle))] bg-[rgb(var(--surface))] p-3.5">
                 <ShieldCheck className="mt-0.5 h-5 w-5 flex-shrink-0 text-[rgb(var(--accent))]" />
                 <p className="text-xs text-[rgb(var(--muted))]">

apps/desktop/src/lib/api/gateway.ts

@@ -315,8 +315,14 @@ export interface ApiKeyInfo {
  * Register a pre-approved client authenticated by an API key.
  * The returned key is shown once and never retrievable again.
  */
-export async function registerApiKeyClient(name: string): Promise<RegisteredApiKeyClient> {
-  return apiCall('register_api_key_client', { name });
+export async function registerApiKeyClient(
+  name: string,
+  lockedSpaceId?: string | null
+): Promise<RegisteredApiKeyClient> {
+  return apiCall('register_api_key_client', {
+    name,
+    lockedSpaceId: lockedSpaceId ?? null,
+  });
 }
 
 /** Issue an additional API key for an existing client (rotation). Shown once. */

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

@@ -397,6 +397,19 @@ impl FeatureSetResolverService {
         }
     }
 
+    /// Whether a binding is eligible under an optional Space lock.
+    fn binding_matches_space_lock(
+        binding: &mcpmux_core::WorkspaceBinding,
+        space_lock: Option<Uuid>,
+    ) -> bool {
+        space_lock.is_none_or(|lock| binding.space_id == lock)
+    }
+
+    /// Space id used for Unbound / grant lookups when a lock is active.
+    fn unbound_space_id(space_lock: Option<Uuid>, fallback: Uuid) -> Uuid {
+        space_lock.unwrap_or(fallback)
+    }
+
     /// Borrow the session-roots registry. The notifier uses this to GC
     /// dead sessions out of the registry when reaping the corresponding
     /// peer entries — keeping both stores in sync.
@@ -430,6 +443,14 @@ impl FeatureSetResolverService {
             }
         };
 
+        // Tier 0 — Space lock narrows all subsequent tiers to one Space.
+        // It never grants tools by itself; no in-Space match still → Unbound.
+        let space_lock = match client_id {
+            Some(cid) => self.client_repo.get_locked_space(cid).await?,
+            None => None,
+        };
+        let deny_space_id = Self::unbound_space_id(space_lock, default_space_id);
+
         // Tier 1 / 1b / 1c — branches on roots-capable + roots-arrived state.
         if let Some(sid) = session_id {
             let roots = self.session_roots.get(sid);
@@ -468,27 +489,35 @@ impl FeatureSetResolverService {
                     .find_binding_for_roots(&reported_roots, client_id, request_machine_id)
                     .await?
                 {
+                    if Self::binding_matches_space_lock(&binding, space_lock) {
+                        debug!(
+                            workspace_root = %binding.workspace_root,
+                            space_id = %binding.space_id,
+                            feature_sets = ?binding.feature_set_ids,
+                            "[FeatureSetResolver] resolved via WorkspaceBinding",
+                        );
+                        return Ok(ResolvedFeatureSet {
+                            feature_set_ids: binding.feature_set_ids,
+                            space_id: Some(binding.space_id),
+                            source: ResolutionSource::WorkspaceBinding,
+                        });
+                    }
                     debug!(
-                        workspace_root = %binding.workspace_root,
-                        space_id = %binding.space_id,
-                        feature_sets = ?binding.feature_set_ids,
-                        "[FeatureSetResolver] resolved via WorkspaceBinding",
+                        binding_space = %binding.space_id,
+                        ?space_lock,
+                        "[FeatureSetResolver] path binding outside locked Space — ignored",
                     );
-                    return Ok(ResolvedFeatureSet {
-                        feature_set_ids: binding.feature_set_ids,
-                        space_id: Some(binding.space_id),
-                        source: ResolutionSource::WorkspaceBinding,
-                    });
                 }
-                // Tier 1b: had roots, no binding. The folder is unmapped —
-                // deny by default. Scope `space_id` to the Space whose base
-                // directory claims the root (longest-prefix), if any; otherwise
-                // the global default Space. Upstream emits WorkspaceNeedsBinding
-                // so the user can attach an explicit binding.
-                let target_space = self
-                    .space_for_roots(&reported_roots)
-                    .await?
-                    .unwrap_or(default_space_id);
+                // Tier 1b: had roots, no binding (or binding outside lock).
+                // The folder is unmapped — deny by default. When locked, scope
+                // `space_id` to the locked Space; otherwise longest-prefix base dir.
+                let target_space = if space_lock.is_some() {
+                    deny_space_id
+                } else {
+                    self.space_for_roots(&reported_roots)
+                        .await?
+                        .unwrap_or(default_space_id)
+                };
                 debug!(
                     %target_space,
                     scoped_by_base_dir = target_space != default_space_id,
@@ -525,7 +554,7 @@ impl FeatureSetResolverService {
                     );
                     return Ok(ResolvedFeatureSet {
                         feature_set_ids: vec![],
-                        space_id: Some(default_space_id),
+                        space_id: Some(deny_space_id),
                         source: ResolutionSource::PendingRoots,
                     });
                 }
@@ -538,7 +567,7 @@ impl FeatureSetResolverService {
                     capability = ?roots_capable_known,
                     "[FeatureSetResolver] pending-roots grace lapsed, no root reported — Unbound",
                 );
-                return Ok(self.unbound(default_space_id));
+                return Ok(self.unbound(deny_space_id));
             }
         }
 
@@ -548,17 +577,24 @@ impl FeatureSetResolverService {
                 .find_binding_for_client_id(cid, request_machine_id)
                 .await?
             {
+                if Self::binding_matches_space_lock(&binding, space_lock) {
+                    debug!(
+                        client_id = %cid,
+                        space_id = %binding.space_id,
+                        feature_sets = ?binding.feature_set_ids,
+                        "[FeatureSetResolver] resolved via id-type WorkspaceBinding",
+                    );
+                    return Ok(ResolvedFeatureSet {
+                        feature_set_ids: binding.feature_set_ids,
+                        space_id: Some(binding.space_id),
+                        source: ResolutionSource::WorkspaceBinding,
+                    });
+                }
                 debug!(
-                    client_id = %cid,
-                    space_id = %binding.space_id,
-                    feature_sets = ?binding.feature_set_ids,
-                    "[FeatureSetResolver] resolved via id-type WorkspaceBinding",
+                    binding_space = %binding.space_id,
+                    ?space_lock,
+                    "[FeatureSetResolver] id binding outside locked Space — ignored",
                 );
-                return Ok(ResolvedFeatureSet {
-                    feature_set_ids: binding.feature_set_ids,
-                    space_id: Some(binding.space_id),
-                    source: ResolutionSource::WorkspaceBinding,
-                });
             }
         }
 
@@ -567,25 +603,26 @@ impl FeatureSetResolverService {
         // (the desktop UI's preview HTTP path lands here too). Consult the
         // per-client grant table.
         if let Some(cid) = client_id {
+            let grant_space_id = deny_space_id;
             // Propagate storage errors instead of treating them as "no
             // grants": a transient DB failure must surface as a request
             // error, not a silent deny (which would also record a `None`
             // fingerprint and fire a spurious Deny→Grant flip-notification
             // cycle once the error clears).
             let grants = self
                 .client_repo
-                .get_grants_for_space(cid, &default_space_id.to_string())
+                .get_grants_for_space(cid, &grant_space_id.to_string())
                 .await?;
             if !grants.is_empty() {
                 debug!(
                     client_id = %cid,
-                    space_id = %default_space_id,
+                    space_id = %grant_space_id,
                     grant_count = grants.len(),
                     "[FeatureSetResolver] resolved via ClientGrant",
                 );
                 return Ok(ResolvedFeatureSet {
                     feature_set_ids: grants,
-                    space_id: Some(default_space_id),
+                    space_id: Some(grant_space_id),
                     source: ResolutionSource::ClientGrant,
                 });
             }
@@ -595,10 +632,11 @@ impl FeatureSetResolverService {
         // tools are appended unconditionally by the request handler regardless,
         // so the LLM can always self-bind / ask the user for a grant from here.
         debug!(
-            space_id = %default_space_id,
+            space_id = %deny_space_id,
             ?client_id,
+            ?space_lock,
             "[FeatureSetResolver] no roots + no id binding + no grants — Unbound",
         );
-        Ok(self.unbound(default_space_id))
+        Ok(self.unbound(deny_space_id))
     }
 }

crates/mcpmux-storage/src/database.rs

@@ -218,6 +218,11 @@ const MIGRATIONS: &[Migration] = &[
         name: "workspace_binding_type",
         sql: include_str!("migrations/037_workspace_binding_type.sql"),
     },
+    Migration {
+        version: 38,
+        name: "inbound_client_locked_space",
+        sql: include_str!("migrations/038_inbound_client_locked_space.sql"),
+    },
 ];
 
 /// SQLite database wrapper.
@@ -758,7 +763,7 @@ mod tests {
                 |row| row.get(0),
             )
             .unwrap();
-        assert_eq!(version, 37);
+        assert_eq!(version, 38);
 
         let v16_name: String = db
             .conn

crates/mcpmux-storage/src/migrations/038_inbound_client_locked_space.sql

@@ -0,0 +1,9 @@
+-- Migration 038: Optional locked_space_id on inbound_clients.
+--
+-- Confines an API-key (or other inbound) client to one Space. The resolver
+-- treats this as a narrowing filter — bindings/grants outside the locked
+-- Space are ignored; no in-Space match still resolves to Unbound.
+
+ALTER TABLE inbound_clients ADD COLUMN locked_space_id TEXT REFERENCES spaces(id) ON DELETE SET NULL;
+
+CREATE INDEX IF NOT EXISTS idx_inbound_clients_locked_space_id ON inbound_clients(locked_space_id);

crates/mcpmux-storage/src/repositories/inbound_client_repository.rs

@@ -469,6 +469,37 @@ impl InboundClientRepository {
         Ok(machine_id_str.and_then(|s| Uuid::parse_str(&s).ok()))
     }
 
+    /// Read the Space lock assigned to an inbound client, if any.
+    pub async fn get_locked_space(&self, client_id: &str) -> Result<Option<Uuid>> {
+        let db = self.db.lock().await;
+        let conn = db.connection();
+        let locked_space_str: Option<String> = conn
+            .query_row(
+                "SELECT locked_space_id FROM inbound_clients WHERE client_id = ?1",
+                params![client_id],
+                |row| row.get(0),
+            )
+            .ok();
+        Ok(locked_space_str.and_then(|s| Uuid::parse_str(&s).ok()))
+    }
+
+    /// Assign or clear the Space lock for an inbound client.
+    pub async fn set_locked_space(&self, client_id: &str, space_id: Option<Uuid>) -> Result<()> {
+        let db = self.db.lock().await;
+        let conn = db.connection();
+        let now = chrono::Utc::now().format("%Y-%m-%dT%H:%M:%SZ").to_string();
+        let space_id_str = space_id.map(|id| id.to_string());
+        conn.execute(
+            "UPDATE inbound_clients SET locked_space_id = ?1, updated_at = ?2 WHERE client_id = ?3",
+            params![space_id_str, now, client_id],
+        )?;
+        debug!(
+            "[OAuth] Set locked_space_id for client {}: {:?}",
+            client_id, space_id
+        );
+        Ok(())
+    }
+
     /// Assign or clear the machine id for an inbound OAuth client.
     pub async fn set_machine_id(&self, client_id: &str, machine_id: Option<Uuid>) -> Result<()> {
         let db = self.db.lock().await;