feat: generalized id mappings + lock-confine resolver (P2)

Mappings are now keyed by a folder PATH or an arbitrary ID string
(BindingType; migration 021). The FeatureSet resolver implements the full
precedence:
  - locked client -> Space is ALWAYS the locked one; the header only selects a
    FeatureSet *within* it (a foreign-Space header is ignored -> locked Starter).
  - unlocked -> header (path/id) > clientId-keyed binding > default-Space Starter.

Adds binding_type to the domain + repo (find_by_id_key + path-scoped
find_exact_for_roots), get/set_locked_space, and migration 022 for
inbound_clients.locked_space_id (fixes P1 lock-to-space, which referenced a
column that did not yet exist). The binding Tauri commands accept id mappings.

Covered by storage + resolver-precedence tests (31 resolver cases green,
incl. id-binding, clientId routing, and all three lock-confine cases).

Signed-off-by: Mohammod Al Amin Ashik <maa.ashik00@gmail.com>

Author: its-mash

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

@@ -8,8 +8,8 @@ use std::collections::{HashMap, HashSet};
 use std::sync::Arc;
 
 use mcpmux_core::{
-    validate_workspace_root as validate_root, DomainEvent, FeatureSet, FeatureSetType, MemberMode,
-    MemberType, ServerFeature, WorkspaceBinding, WorkspaceRootValidation,
+    validate_workspace_root as validate_root, BindingType, DomainEvent, FeatureSet, FeatureSetType,
+    MemberMode, MemberType, ServerFeature, WorkspaceBinding, WorkspaceRootValidation,
 };
 use serde::{Deserialize, Serialize};
 use tauri::State;
@@ -54,6 +54,8 @@ async fn emit_binding_changed(
 pub struct WorkspaceBindingDto {
     pub id: String,
     pub workspace_root: String,
+    /// `path` (folder, normalized) or `id` (arbitrary exact-match key).
+    pub binding_type: String,
     pub space_id: String,
     pub feature_set_ids: Vec<String>,
     pub created_at: String,
@@ -65,6 +67,7 @@ impl From<WorkspaceBinding> for WorkspaceBindingDto {
         Self {
             id: b.id.to_string(),
             workspace_root: b.workspace_root,
+            binding_type: b.binding_type.as_str().to_string(),
             space_id: b.space_id.to_string(),
             feature_set_ids: b.feature_set_ids,
             created_at: b.created_at.to_rfc3339(),
@@ -83,6 +86,10 @@ pub struct WorkspaceBindingInput {
     pub workspace_root: String,
     pub space_id: String,
     pub feature_set_ids: Vec<String>,
+    /// `path` (default — folder, normalized + validated) or `id` (arbitrary
+    /// exact-match key, taken verbatim). Optional for backward compatibility.
+    #[serde(default)]
+    pub binding_type: Option<String>,
 }
 
 fn parse_space_id(input: &WorkspaceBindingInput) -> Result<Uuid, String> {
@@ -229,6 +236,26 @@ fn normalize_and_validate(raw: &str) -> Result<String, String> {
     }
 }
 
+/// Resolve the storage key + type from the input. `path` bindings are
+/// normalized + validated (rejecting relative paths, filesystem roots, …);
+/// `id` bindings take the raw string verbatim (any non-empty label a headless
+/// client sends in `X-Mcpmux-Workspace`, e.g. a client id or machine name).
+fn resolve_key_and_type(input: &WorkspaceBindingInput) -> Result<(String, BindingType), String> {
+    match input.binding_type.as_deref() {
+        Some("id") => {
+            let key = input.workspace_root.trim();
+            if key.is_empty() {
+                return Err("Mapping id cannot be empty".into());
+            }
+            Ok((key.to_string(), BindingType::Id))
+        }
+        _ => Ok((
+            normalize_and_validate(&input.workspace_root)?,
+            BindingType::Path,
+        )),
+    }
+}
+
 /// Create a binding. Path is normalized + validated server-side so the UI
 /// can pass raw input (Windows paths, file:// URIs, trailing slashes).
 #[tauri::command]
@@ -239,23 +266,26 @@ pub async fn create_workspace_binding(
 ) -> Result<WorkspaceBindingDto, String> {
     let space_id = parse_space_id(&input)?;
     let feature_set_ids = validate_fs_list(&input)?;
-    let normalized = normalize_and_validate(&input.workspace_root)?;
+    let (key, binding_type) = resolve_key_and_type(&input)?;
 
-    // Reject a duplicate folder up front with a readable message. The schema
+    // Reject a duplicate key up front with a readable message. The schema
     // already enforces `UNIQUE(workspace_root)`, but that surfaces an opaque
     // SQLite constraint error — this gives the UI something a user can act on.
     let existing = state
         .workspace_binding_repository
         .list()
         .await
         .map_err(|e| e.to_string())?;
-    if existing.iter().any(|b| b.workspace_root == normalized) {
+    if existing.iter().any(|b| b.workspace_root == key) {
         return Err(format!(
-            "A mapping already exists for {normalized}. Edit the existing mapping instead of adding a second one."
+            "A mapping already exists for {key}. Edit the existing mapping instead of adding a second one."
         ));
     }
 
-    let binding = WorkspaceBinding::new_multi(normalized.clone(), space_id, feature_set_ids);
+    let binding = match binding_type {
+        BindingType::Id => WorkspaceBinding::new_id(key.clone(), space_id, feature_set_ids),
+        BindingType::Path => WorkspaceBinding::new_multi(key.clone(), space_id, feature_set_ids),
+    };
 
     state
         .workspace_binding_repository
@@ -292,9 +322,9 @@ pub async fn update_workspace_binding(
     let id_uuid = Uuid::parse_str(&id).map_err(|e| e.to_string())?;
     let space_id = parse_space_id(&input)?;
     let feature_set_ids = validate_fs_list(&input)?;
-    let normalized = normalize_and_validate(&input.workspace_root)?;
+    let (key, binding_type) = resolve_key_and_type(&input)?;
 
-    // If the edit moved the folder onto a path another mapping already owns,
+    // If the edit moved the mapping onto a key another mapping already owns,
     // reject with a readable message rather than tripping the DB UNIQUE
     // constraint. Exclude this binding's own row.
     let all = state
@@ -304,10 +334,10 @@ pub async fn update_workspace_binding(
         .map_err(|e| e.to_string())?;
     if all
         .iter()
-        .any(|b| b.id != id_uuid && b.workspace_root == normalized)
+        .any(|b| b.id != id_uuid && b.workspace_root == key)
     {
         return Err(format!(
-            "Another mapping already uses {normalized}. Pick a different folder."
+            "Another mapping already uses {key}. Pick a different key."
         ));
     }
 
@@ -321,7 +351,8 @@ pub async fn update_workspace_binding(
 
     let updated = WorkspaceBinding {
         id: existing.id,
-        workspace_root: normalized,
+        workspace_root: key,
+        binding_type,
         space_id,
         feature_set_ids,
         created_at: existing.created_at,

crates/mcpmux-core/src/domain/mod.rs

@@ -39,5 +39,5 @@ pub use server_log::*;
 pub use space::*;
 pub use workspace_binding::{
     longest_matching_base, normalize_workspace_root, path_is_within, validate_workspace_root,
-    WorkspaceBinding, WorkspaceRootValidation,
+    BindingType, WorkspaceBinding, WorkspaceRootValidation,
 };

crates/mcpmux-core/src/domain/workspace_binding.rs

@@ -25,6 +25,38 @@ use chrono::{DateTime, Utc};
 use serde::{Deserialize, Serialize};
 use uuid::Uuid;
 
+/// How a binding's `workspace_root` key is matched against a request.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
+#[serde(rename_all = "lowercase")]
+pub enum BindingType {
+    /// A normalized absolute folder path (the original behaviour). Matched
+    /// case-/separator-insensitively via [`normalize_workspace_root`].
+    #[default]
+    Path,
+    /// An arbitrary exact-match string — a client id, machine name, or any
+    /// label a headless/remote client sends in `X-Mcpmux-Workspace`. Matched
+    /// verbatim (no path normalization).
+    Id,
+}
+
+impl BindingType {
+    pub fn as_str(&self) -> &'static str {
+        match self {
+            BindingType::Path => "path",
+            BindingType::Id => "id",
+        }
+    }
+
+    /// Parse from storage; unknown values fall back to `Path` (the default for
+    /// pre-`binding_type` rows).
+    pub fn parse(s: &str) -> Self {
+        match s {
+            "id" => BindingType::Id,
+            _ => BindingType::Path,
+        }
+    }
+}
+
 /// A binding between a normalized workspace root and the FeatureSet(s) it
 /// resolves to. `feature_set_ids` MAY be empty — an empty list is a valid
 /// "no Space tools" mapping (the folder still routes to this Space; built-in
@@ -33,6 +65,8 @@ use uuid::Uuid;
 pub struct WorkspaceBinding {
     pub id: Uuid,
     pub workspace_root: String,
+    /// Whether `workspace_root` is a filesystem path or an arbitrary id key.
+    pub binding_type: BindingType,
     pub space_id: Uuid,
     /// Order matters for UI rendering only — the resolver treats them as
     /// a set. Stored in the `workspace_binding_feature_sets` junction
@@ -63,12 +97,23 @@ impl WorkspaceBinding {
         Self {
             id: Uuid::new_v4(),
             workspace_root: workspace_root.into(),
+            binding_type: BindingType::Path,
             space_id,
             feature_set_ids,
             created_at: now,
             updated_at: now,
         }
     }
+
+    /// Construct an **id-keyed** binding: `key` is matched verbatim (exact
+    /// string, no path normalization) rather than as a folder. Used to route
+    /// headless/remote clients by a client id or an arbitrary label.
+    pub fn new_id(key: impl Into<String>, space_id: Uuid, feature_set_ids: Vec<String>) -> Self {
+        Self {
+            binding_type: BindingType::Id,
+            ..Self::new_multi(key, space_id, feature_set_ids)
+        }
+    }
 }
 
 // ============================================================================

crates/mcpmux-core/src/repository/mod.rs

@@ -276,6 +276,12 @@ pub trait WorkspaceBindingRepository: Send + Sync {
         &self,
         candidate_roots: &[String],
     ) -> RepoResult<Option<WorkspaceBinding>>;
+
+    /// Resolve an **id-keyed** binding by exact-string match (no path
+    /// normalization). Used to route headless/remote clients by a client id or
+    /// an arbitrary label sent in `X-Mcpmux-Workspace`. Only `BindingType::Id`
+    /// bindings are considered, so a folder path can never collide with a label.
+    async fn find_by_id_key(&self, key: &str) -> RepoResult<Option<WorkspaceBinding>>;
 }
 
 /// Credential repository trait (local-only, never synced)

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

@@ -95,7 +95,8 @@ use std::time::Duration;
 
 use anyhow::Result;
 use mcpmux_core::{
-    FeatureSetRepository, SpaceBaseDirRepository, SpaceRepository, WorkspaceBindingRepository,
+    FeatureSetRepository, SpaceBaseDirRepository, SpaceRepository, WorkspaceBinding,
+    WorkspaceBindingRepository,
 };
 use mcpmux_storage::InboundClientRepository;
 use serde::Serialize;
@@ -281,6 +282,65 @@ impl FeatureSetResolverService {
         })
     }
 
+    /// Resolve a binding from header/root candidate keys: a **path** binding
+    /// (exact normalized match) or, failing that, an **id** binding (exact
+    /// verbatim match — a client id or arbitrary label). First hit wins. Path
+    /// and id bindings live in disjoint namespaces in the repo, so this never
+    /// double-matches.
+    async fn mapping_binding_for_roots(
+        &self,
+        roots: &[String],
+    ) -> Result<Option<WorkspaceBinding>> {
+        if let Some(b) = self.binding_repo.find_exact_for_roots(roots).await? {
+            return Ok(Some(b));
+        }
+        for r in roots {
+            if let Some(b) = self.binding_repo.find_by_id_key(r).await? {
+                return Ok(Some(b));
+            }
+        }
+        Ok(None)
+    }
+
+    /// Resolve a client locked to Space `locked`. The Space is fixed to
+    /// `locked`; the header/roots may still pick the FeatureSet, but only when
+    /// their binding lives in `locked`. A header whose binding resolves to a
+    /// different Space — or no header at all — falls back to `locked`'s Starter.
+    /// A locked client never touches the roots-pending or client-grant tiers.
+    async fn resolve_locked(
+        &self,
+        session_id: Option<&str>,
+        locked: Uuid,
+    ) -> Result<ResolvedFeatureSet> {
+        if let Some(sid) = session_id {
+            if let Some(roots) = self.session_roots.get(sid) {
+                if !roots.is_empty() {
+                    if let Some(binding) = self.mapping_binding_for_roots(&roots).await? {
+                        if binding.space_id == locked {
+                            debug!(
+                                %locked,
+                                workspace_root = %binding.workspace_root,
+                                "[FeatureSetResolver] locked client — header binding within locked Space",
+                            );
+                            return Ok(ResolvedFeatureSet {
+                                feature_set_ids: binding.feature_set_ids,
+                                space_id: Some(locked),
+                                source: ResolutionSource::WorkspaceBinding,
+                            });
+                        }
+                        debug!(
+                            %locked,
+                            binding_space = %binding.space_id,
+                            "[FeatureSetResolver] locked client — header binding in a different Space; ignored",
+                        );
+                    }
+                }
+            }
+        }
+        // No header, or its binding is outside the locked Space → locked Starter.
+        self.default_fallback(locked).await
+    }
+
     /// 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.
@@ -311,6 +371,23 @@ impl FeatureSetResolverService {
             }
         };
 
+        // Lock-confine: a client locked to Space L only ever resolves to L. The
+        // header/roots may still pick a FeatureSet *within* L; a binding that
+        // resolves to a different Space — or no header — yields L's Starter.
+        // Bypasses the roots-pending and grant tiers entirely.
+        if let Some(cid) = client_id {
+            if let Some(locked) = self.client_repo.get_locked_space(cid).await? {
+                match locked.parse::<Uuid>() {
+                    Ok(locked_uuid) => return self.resolve_locked(session_id, locked_uuid).await,
+                    Err(e) => warn!(
+                        client_id = %cid,
+                        locked_space = %locked,
+                        "[FeatureSetResolver] client locked to unparseable space id: {e}",
+                    ),
+                }
+            }
+        }
+
         // Tier 1 / 1b / 1c — branches on roots-capable + roots-arrived state.
         if let Some(sid) = session_id {
             let roots = self.session_roots.get(sid);
@@ -345,11 +422,9 @@ impl FeatureSetResolverService {
             // (no ancestor inheritance).
             if has_roots {
                 let reported_roots = roots.expect("has_roots implies Some");
-                if let Some(binding) = self
-                    .binding_repo
-                    .find_exact_for_roots(&reported_roots)
-                    .await?
-                {
+                // Exact binding match: a path binding (normalized folder) or an
+                // id binding (verbatim label / client-id sent in the header).
+                if let Some(binding) = self.mapping_binding_for_roots(&reported_roots).await? {
                     debug!(
                         workspace_root = %binding.workspace_root,
                         space_id = %binding.space_id,
@@ -433,6 +508,23 @@ impl FeatureSetResolverService {
         // (the desktop UI's preview HTTP path lands here too). Consult the
         // per-client grant table.
         if let Some(cid) = client_id {
+            // clientId-keyed mapping (auto-created for API-key clients): when no
+            // header/roots selected a binding above, route by the client's own
+            // id. Editor clients have no such binding and fall through to grants.
+            if let Some(binding) = self.binding_repo.find_by_id_key(cid).await? {
+                debug!(
+                    client_id = %cid,
+                    workspace_root = %binding.workspace_root,
+                    space_id = %binding.space_id,
+                    "[FeatureSetResolver] resolved via clientId mapping",
+                );
+                return Ok(ResolvedFeatureSet {
+                    feature_set_ids: binding.feature_set_ids,
+                    space_id: Some(binding.space_id),
+                    source: ResolutionSource::WorkspaceBinding,
+                });
+            }
+
             // 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`

crates/mcpmux-storage/src/database.rs

@@ -133,6 +133,16 @@ const MIGRATIONS: &[Migration] = &[
         name: "inbound_client_api_keys",
         sql: include_str!("migrations/020_inbound_client_api_keys.sql"),
     },
+    Migration {
+        version: 21,
+        name: "binding_type",
+        sql: include_str!("migrations/021_binding_type.sql"),
+    },
+    Migration {
+        version: 22,
+        name: "inbound_client_locked_space",
+        sql: include_str!("migrations/022_inbound_client_locked_space.sql"),
+    },
 ];
 
 /// SQLite database wrapper.

crates/mcpmux-storage/src/migrations/021_binding_type.sql

@@ -0,0 +1,11 @@
+-- Migration 021: workspace binding type (path vs id)
+--
+-- Generalizes mappings beyond filesystem folders. A binding's `workspace_root`
+-- is now a routing KEY that is either:
+--   * 'path' — a normalized absolute folder path (the original behaviour), or
+--   * 'id'   — an arbitrary exact-match string (a client id, machine name, or
+--              any label a headless/remote client sends in X-Mcpmux-Workspace).
+-- Existing rows are folder paths, so they default to 'path' (backward
+-- compatible). Path keys are normalized + case-folded before comparison;
+-- id keys are matched verbatim.
+ALTER TABLE workspace_bindings ADD COLUMN binding_type TEXT NOT NULL DEFAULT 'path';