feat: register API-key clients + key-management commands

Phase 1. Host-side surface to mint/manage API keys:
- Tauri commands: register_api_key_client (creates a Preregistered + approved
  client, issues a key shown once), create_client_api_key (rotation),
  list_client_api_keys, revoke_client_api_key.
- TS wrappers + RegisteredApiKeyClient / ApiKeyInfo types.

The generated key (mcpk_ + 256 bits) is returned once; only its SHA-256 hash is
stored. A remote client then authenticates with `Authorization: Bearer <key>`.

The locked_space wiring (set_locked_space/get_locked_space repo methods,
register_api_key_client's locked_space_id param, and the lockedSpaceId TS field)
is deferred to P2, where migration 022 introduces the locked_space_id column
(Strategy Y). P1 ships pure API-key auth with migration 020 only.

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

Author: its-mash

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

@@ -927,6 +927,221 @@ pub async fn delete_oauth_client(
     Ok(())
 }
 
+// =============================================================================
+// API-key clients (manually registered, host-issued credentials)
+//
+// A "preregistered", pre-approved inbound client authenticated by a long-lived
+// API key. Unlike DCR clients it skips the browser-consent deep link, so
+// headless/remote clients can connect with just the key — the secure path when
+// the gateway is exposed over the network.
+// =============================================================================
+
+/// A newly-registered API-key client. `api_key` is returned ONCE at creation —
+/// McpMux stores only its SHA-256 hash and can never show it again.
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RegisteredApiKeyClient {
+    pub client_id: String,
+    pub client_name: String,
+    pub api_key: String,
+    pub key_prefix: String,
+}
+
+/// API-key metadata for display (never includes the secret).
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ApiKeyInfo {
+    pub key_id: String,
+    pub key_prefix: String,
+    pub label: Option<String>,
+    pub revoked: bool,
+    pub last_used_at: Option<String>,
+    pub created_at: String,
+}
+
+/// Generate a strong API key: `mcpk_` + 256 bits of v4-UUID randomness.
+/// Returns `(key_id, plaintext, key_prefix)`. Only the hash is ever stored.
+fn generate_api_key() -> (String, String, String) {
+    let key_id = uuid::Uuid::new_v4().to_string();
+    let secret = format!(
+        "{}{}",
+        uuid::Uuid::new_v4().simple(),
+        uuid::Uuid::new_v4().simple()
+    );
+    let plaintext = format!("mcpk_{secret}");
+    let key_prefix: String = plaintext.chars().take(13).collect(); // "mcpk_" + 8 chars
+    (key_id, plaintext, key_prefix)
+}
+
+/// Register a new pre-approved client authenticated by an API key. The returned
+/// `api_key` is shown once and never stored.
+#[tauri::command]
+pub async fn register_api_key_client(
+    gateway_state: State<'_, Arc<RwLock<GatewayAppState>>>,
+    name: String,
+) -> Result<RegisteredApiKeyClient, String> {
+    let app_state = gateway_state.read().await;
+    let Some(ref gw_state) = app_state.gateway_state else {
+        return Err("Gateway not running".to_string());
+    };
+    let state = gw_state.read().await;
+    let Some(repo) = state.inbound_client_repository() else {
+        return Err("Database not available".to_string());
+    };
+
+    let trimmed = name.trim();
+    if trimmed.is_empty() {
+        return Err("Client name is required".to_string());
+    }
+
+    let now = chrono::Utc::now().to_rfc3339();
+    let client_id = format!("mcp_{}", &uuid::Uuid::new_v4().simple().to_string()[..8]);
+    let client = mcpmux_storage::InboundClient {
+        client_id: client_id.clone(),
+        registration_type: mcpmux_storage::RegistrationType::Preregistered,
+        client_name: trimmed.to_string(),
+        client_alias: None,
+        redirect_uris: vec![],
+        grant_types: vec![],
+        response_types: vec![],
+        token_endpoint_auth_method: "none".to_string(),
+        scope: None,
+        approved: true,
+        logo_uri: None,
+        client_uri: None,
+        software_id: None,
+        software_version: None,
+        metadata_url: None,
+        metadata_cached_at: None,
+        metadata_cache_ttl: None,
+        last_seen: None,
+        created_at: now.clone(),
+        updated_at: now,
+        reports_roots: false,
+        roots_capability_known: false,
+    };
+    repo.save_client(&client)
+        .await
+        .map_err(|e| format!("Failed to create client: {}", e))?;
+
+    let (key_id, plaintext, key_prefix) = generate_api_key();
+    repo.create_api_key(&key_id, &client_id, &plaintext, &key_prefix, None, None)
+        .await
+        .map_err(|e| format!("Failed to create API key: {}", e))?;
+
+    info!(
+        "[OAuth] Registered API-key client {} ({})",
+        trimmed, client_id
+    );
+
+    Ok(RegisteredApiKeyClient {
+        client_id,
+        client_name: trimmed.to_string(),
+        api_key: plaintext,
+        key_prefix,
+    })
+}
+
+/// Issue an additional API key for an existing client (rotation). Returns the
+/// new key plaintext once.
+#[tauri::command]
+pub async fn create_client_api_key(
+    gateway_state: State<'_, Arc<RwLock<GatewayAppState>>>,
+    client_id: String,
+    label: Option<String>,
+) -> Result<RegisteredApiKeyClient, String> {
+    let app_state = gateway_state.read().await;
+    let Some(ref gw_state) = app_state.gateway_state else {
+        return Err("Gateway not running".to_string());
+    };
+    let state = gw_state.read().await;
+    let Some(repo) = state.inbound_client_repository() else {
+        return Err("Database not available".to_string());
+    };
+
+    let Some(client) = repo
+        .get_client(&client_id)
+        .await
+        .map_err(|e| format!("Failed to load client: {}", e))?
+    else {
+        return Err("Client not found".to_string());
+    };
+
+    let (key_id, plaintext, key_prefix) = generate_api_key();
+    repo.create_api_key(
+        &key_id,
+        &client_id,
+        &plaintext,
+        &key_prefix,
+        label.as_deref(),
+        None,
+    )
+    .await
+    .map_err(|e| format!("Failed to create API key: {}", e))?;
+
+    Ok(RegisteredApiKeyClient {
+        client_id,
+        client_name: client.client_name,
+        api_key: plaintext,
+        key_prefix,
+    })
+}
+
+/// List a client's API keys (metadata only — never the secret).
+#[tauri::command]
+pub async fn list_client_api_keys(
+    gateway_state: State<'_, Arc<RwLock<GatewayAppState>>>,
+    client_id: String,
+) -> Result<Vec<ApiKeyInfo>, String> {
+    let app_state = gateway_state.read().await;
+    let Some(ref gw_state) = app_state.gateway_state else {
+        return Err("Gateway not running".to_string());
+    };
+    let state = gw_state.read().await;
+    let Some(repo) = state.inbound_client_repository() else {
+        return Err("Database not available".to_string());
+    };
+
+    let keys = repo
+        .list_api_keys(&client_id)
+        .await
+        .map_err(|e| format!("Failed to list API keys: {}", e))?;
+
+    Ok(keys
+        .into_iter()
+        .map(|k| ApiKeyInfo {
+            key_id: k.key_id,
+            key_prefix: k.key_prefix,
+            label: k.label,
+            revoked: k.revoked,
+            last_used_at: k.last_used_at,
+            created_at: k.created_at,
+        })
+        .collect())
+}
+
+/// Revoke a single API key (it can never authenticate again).
+#[tauri::command]
+pub async fn revoke_client_api_key(
+    gateway_state: State<'_, Arc<RwLock<GatewayAppState>>>,
+    key_id: String,
+) -> Result<(), String> {
+    let app_state = gateway_state.read().await;
+    let Some(ref gw_state) = app_state.gateway_state else {
+        return Err("Gateway not running".to_string());
+    };
+    let state = gw_state.read().await;
+    let Some(repo) = state.inbound_client_repository() else {
+        return Err("Database not available".to_string());
+    };
+
+    repo.revoke_api_key(&key_id)
+        .await
+        .map_err(|e| format!("Failed to revoke API key: {}", e))?;
+    info!("[OAuth] Revoked API key {}", key_id);
+    Ok(())
+}
+
 /// Open a URL without flashing a terminal window (Windows-specific)
 #[cfg(target_os = "windows")]
 fn open_url_no_flash(url: &str) -> Result<(), String> {

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

@@ -984,6 +984,10 @@ pub fn run() {
             commands::approve_oauth_client,
             commands::update_oauth_client,
             commands::delete_oauth_client,
+            commands::register_api_key_client,
+            commands::create_client_api_key,
+            commands::list_client_api_keys,
+            commands::revoke_client_api_key,
             commands::open_url,
             // Per-client grants for the rootless fallback path
             commands::get_oauth_client_grants,

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

@@ -151,10 +151,7 @@ export async function restartGateway(opts?: {
 /**
  * Export config for a client.
  */
-export async function exportConfig(
-  format: ExportFormat,
-  clientId?: string
-): Promise<string> {
+export async function exportConfig(format: ExportFormat, clientId?: string): Promise<string> {
   return invoke('export_config', { format, clientId });
 }
 
@@ -181,7 +178,11 @@ export async function connectServer(serverId: string): Promise<void> {
  * @param spaceId - The space ID (required for proper space isolation)
  * @param logout - If true, also delete stored credentials (OAuth tokens)
  */
-export async function disconnectServer(serverId: string, spaceId: string, logout?: boolean): Promise<void> {
+export async function disconnectServer(
+  serverId: string,
+  spaceId: string,
+  logout?: boolean
+): Promise<void> {
   return invoke('disconnect_server', { serverId, spaceId, logout });
 }
 
@@ -199,13 +200,13 @@ export type RegistrationType = 'cimd' | 'dcr' | 'preregistered';
 
 /**
  * Inbound client (unified OAuth + MCP model)
- * 
+ *
  * Represents apps connecting TO McpMux (e.g., Cursor, VS Code, Claude Desktop).
  * Supports three MCP registration approaches:
  * - CIMD: Client ID Metadata Documents (client_id is a URL)
  * - DCR: Dynamic Client Registration (server generates client_id)
  * - Preregistered: Server pre-configures client_id
- * 
+ *
  * Per RFC 7591, clients self-identify via metadata they provide.
  * Use `logo_uri`, `software_id`, and `client_name` for client identification.
  */
@@ -216,20 +217,20 @@ export interface OAuthClient {
   client_alias: string | null;
   redirect_uris: string[];
   scope: string | null;
-  
+
   // Approval status - true if user has explicitly approved this client
   approved: boolean;
-  
+
   // RFC 7591 Client Metadata (use these for client identification)
-  logo_uri?: string | null;  // URL for client's logo
-  client_uri?: string | null;  // URL of client's homepage
-  software_id?: string | null;  // Unique identifier (e.g., "com.cursor.app")
-  software_version?: string | null;  // Client software version
-  
+  logo_uri?: string | null; // URL for client's logo
+  client_uri?: string | null; // URL of client's homepage
+  software_id?: string | null; // Unique identifier (e.g., "com.cursor.app")
+  software_version?: string | null; // Client software version
+
   // CIMD-specific fields (only used when registration_type='cimd')
-  metadata_url?: string | null;  // URL where metadata was fetched
-  metadata_cached_at?: string | null;  // When we last fetched
-  metadata_cache_ttl?: number | null;  // Cache duration in seconds
+  metadata_url?: string | null; // URL where metadata was fetched
+  metadata_cached_at?: string | null; // When we last fetched
+  metadata_cache_ttl?: number | null; // Cache duration in seconds
 
   last_seen: string | null;
   created_at: string;
@@ -302,10 +303,7 @@ export async function deleteOAuthClient(clientId: string): Promise<void> {
  * means the rootless fallback would deny — consumer should render the
  * "no defaults configured" empty state.
  */
-export async function getOAuthClientGrants(
-  clientId: string,
-  spaceId: string
-): Promise<string[]> {
+export async function getOAuthClientGrants(clientId: string, spaceId: string): Promise<string[]> {
   return invoke('get_oauth_client_grants', { clientId, spaceId });
 }
 
@@ -340,6 +338,59 @@ export async function revokeOAuthClientFeatureSet(
   });
 }
 
+// =============================================================================
+// API-key clients (manually registered, host-issued credentials)
+// =============================================================================
+//
+// A pre-approved inbound client authenticated by a long-lived API key. Skips
+// the browser-consent deep link, so headless/remote clients can connect with
+// just the key — the secure path when the gateway is exposed over the network.
+
+/** A newly-registered API-key client. `apiKey` is shown ONCE — store it now. */
+export interface RegisteredApiKeyClient {
+  clientId: string;
+  clientName: string;
+  /** The full key — shown once; afterwards only its hash is kept. */
+  apiKey: string;
+  keyPrefix: string;
+}
+
+/** API-key metadata for display (never the secret). */
+export interface ApiKeyInfo {
+  keyId: string;
+  keyPrefix: string;
+  label: string | null;
+  revoked: boolean;
+  lastUsedAt: string | null;
+  createdAt: string;
+}
+
+/**
+ * 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 invoke('register_api_key_client', { name });
+}
+
+/** Issue an additional API key for an existing client (rotation). Shown once. */
+export async function createClientApiKey(
+  clientId: string,
+  label?: string | null
+): Promise<RegisteredApiKeyClient> {
+  return invoke('create_client_api_key', { clientId, label: label ?? null });
+}
+
+/** List a client's API keys (metadata only — never the secret). */
+export async function listClientApiKeys(clientId: string): Promise<ApiKeyInfo[]> {
+  return invoke('list_client_api_keys', { clientId });
+}
+
+/** Revoke an API key (it can never authenticate again). */
+export async function revokeClientApiKey(keyId: string): Promise<void> {
+  return invoke('revoke_client_api_key', { keyId });
+}
+
 /**
  * Result of bulk server connection.
  */
@@ -394,7 +445,7 @@ export async function refreshOAuthTokensOnStartup(): Promise<RefreshResult> {
 
 /**
  * Open a URL using the system's default handler.
- * 
+ *
  * This is needed for custom protocol URLs (like `cursor://`) that
  * the webview's opener plugin may not be allowed to open directly.
  */