feat(storage): inbound API-key credentials (migration 020 + repo)

Phase 1 of API-key inbound auth (so headless/remote clients authenticate
without the host-only OAuth consent deep link). Adds the
inbound_client_api_keys table — SHA-256 hashes only, never plaintext; multiple
keys per client for rotation — and InboundClientRepository methods
create/validate/list/revoke (validation rejects revoked/expired keys and
touches last_used_at), plus InboundApiKey + ApiKeyAuth types.

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

Author: its-mash

crates/mcpmux-storage/src/database.rs

@@ -128,6 +128,11 @@ const MIGRATIONS: &[Migration] = &[
         name: "space_base_dirs",
         sql: include_str!("migrations/019_space_base_dirs.sql"),
     },
+    Migration {
+        version: 20,
+        name: "inbound_client_api_keys",
+        sql: include_str!("migrations/020_inbound_client_api_keys.sql"),
+    },
 ];
 
 /// SQLite database wrapper.

crates/mcpmux-storage/src/migrations/020_inbound_client_api_keys.sql

@@ -0,0 +1,25 @@
+-- Migration 020: Inbound client API keys
+--
+-- Long-lived, host-issued bearer credentials for manually-registered
+-- (preregistered) inbound clients, so headless/remote clients can authenticate
+-- WITHOUT the interactive OAuth consent flow (the mcpmux:// deep link only
+-- works on the host). Keys are shown once at creation and stored only as a
+-- SHA-256 hash — never in plaintext. Multiple keys per client allow rotation.
+
+CREATE TABLE IF NOT EXISTS inbound_client_api_keys (
+    key_id TEXT PRIMARY KEY,
+    client_id TEXT NOT NULL,
+    key_hash TEXT NOT NULL UNIQUE,   -- SHA-256(presented key), hex
+    key_prefix TEXT NOT NULL,        -- first chars (e.g. "mcpk_ab12") for UI display
+    label TEXT,                      -- optional user-facing name for the key
+    revoked INTEGER NOT NULL DEFAULT 0,
+    last_used_at TEXT,
+    expires_at TEXT,                 -- optional ISO-8601; NULL = no expiry
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    FOREIGN KEY (client_id) REFERENCES inbound_clients(client_id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_api_keys_client ON inbound_client_api_keys(client_id);
+-- Lookups on auth validate by hash and only care about live keys.
+CREATE INDEX IF NOT EXISTS idx_api_keys_hash_live ON inbound_client_api_keys(key_hash) WHERE revoked = 0;

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

@@ -160,6 +160,27 @@ pub struct TokenRecord {
     pub parent_token_id: Option<String>,
 }
 
+/// A stored API-key record. Never exposes the secret — only its display prefix.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct InboundApiKey {
+    pub key_id: String,
+    pub client_id: String,
+    pub key_prefix: String,
+    pub label: Option<String>,
+    pub revoked: bool,
+    pub last_used_at: Option<String>,
+    pub expires_at: Option<String>,
+    pub created_at: String,
+    pub updated_at: String,
+}
+
+/// Identity resolved from a presented API key.
+#[derive(Debug, Clone)]
+pub struct ApiKeyAuth {
+    pub key_id: String,
+    pub client_id: String,
+}
+
 /// OAuth Repository with database persistence
 pub struct InboundClientRepository {
     db: Arc<Mutex<Database>>,
@@ -566,6 +587,126 @@ impl InboundClientRepository {
         hex::encode(hasher.finalize())
     }
 
+    // =========================================================================
+    // Inbound client API keys (long-lived, host-issued bearer credentials)
+    // =========================================================================
+
+    /// SHA-256 hex of an API key — the only form ever persisted. Same algorithm
+    /// as `hash_token`; named separately for intent.
+    pub fn hash_api_key(key: &str) -> String {
+        Self::hash_token(key)
+    }
+
+    /// Persist a freshly-generated API key for a client. The caller generates
+    /// the random `plaintext` (shown to the user once) and a unique `key_id`;
+    /// only the SHA-256 hash + a display prefix are stored.
+    pub async fn create_api_key(
+        &self,
+        key_id: &str,
+        client_id: &str,
+        plaintext: &str,
+        key_prefix: &str,
+        label: Option<&str>,
+        expires_at: Option<&str>,
+    ) -> Result<()> {
+        let now = chrono::Utc::now().to_rfc3339();
+        let hash = Self::hash_api_key(plaintext);
+        let db = self.db.lock().await;
+        let conn = db.connection();
+        conn.execute(
+            "INSERT INTO inbound_client_api_keys
+                (key_id, client_id, key_hash, key_prefix, label, revoked, expires_at, created_at, updated_at)
+             VALUES (?1, ?2, ?3, ?4, ?5, 0, ?6, ?7, ?7)",
+            params![key_id, client_id, hash, key_prefix, label, expires_at, now],
+        )?;
+        info!(
+            "[ApiKey] Created key {} for client {}",
+            key_prefix, client_id
+        );
+        Ok(())
+    }
+
+    /// Validate a presented API key: look up a live (non-revoked, unexpired) key
+    /// by hash, touch `last_used_at`, and return the owning client.
+    pub async fn validate_api_key(&self, presented: &str) -> Result<Option<ApiKeyAuth>> {
+        let hash = Self::hash_api_key(presented);
+        let now = chrono::Utc::now().to_rfc3339();
+        let db = self.db.lock().await;
+        let conn = db.connection();
+
+        let result = conn.query_row(
+            "SELECT key_id, client_id, expires_at
+             FROM inbound_client_api_keys
+             WHERE key_hash = ?1 AND revoked = 0",
+            params![hash],
+            |r| {
+                Ok((
+                    r.get::<_, String>(0)?,
+                    r.get::<_, String>(1)?,
+                    r.get::<_, Option<String>>(2)?,
+                ))
+            },
+        );
+        let (key_id, client_id, expires_at) = match result {
+            Ok(t) => t,
+            Err(rusqlite::Error::QueryReturnedNoRows) => return Ok(None),
+            Err(e) => return Err(e.into()),
+        };
+
+        // ISO-8601 strings compare lexicographically; reject expired keys.
+        if let Some(exp) = expires_at.as_deref() {
+            if exp <= now.as_str() {
+                return Ok(None);
+            }
+        }
+
+        conn.execute(
+            "UPDATE inbound_client_api_keys SET last_used_at = ?1 WHERE key_id = ?2",
+            params![now, key_id],
+        )?;
+        Ok(Some(ApiKeyAuth { key_id, client_id }))
+    }
+
+    /// List a client's API keys (no secrets — prefix + metadata only).
+    pub async fn list_api_keys(&self, client_id: &str) -> Result<Vec<InboundApiKey>> {
+        let db = self.db.lock().await;
+        let conn = db.connection();
+        let mut stmt = conn.prepare(
+            "SELECT key_id, client_id, key_prefix, label, revoked, last_used_at, expires_at, created_at, updated_at
+             FROM inbound_client_api_keys WHERE client_id = ?1 ORDER BY created_at DESC",
+        )?;
+        let rows = stmt.query_map(params![client_id], |r| {
+            Ok(InboundApiKey {
+                key_id: r.get(0)?,
+                client_id: r.get(1)?,
+                key_prefix: r.get(2)?,
+                label: r.get(3)?,
+                revoked: r.get::<_, i32>(4)? != 0,
+                last_used_at: r.get(5)?,
+                expires_at: r.get(6)?,
+                created_at: r.get(7)?,
+                updated_at: r.get(8)?,
+            })
+        })?;
+        let mut keys = Vec::new();
+        for k in rows {
+            keys.push(k?);
+        }
+        Ok(keys)
+    }
+
+    /// Revoke a single API key (irreversible — it can never authenticate again).
+    pub async fn revoke_api_key(&self, key_id: &str) -> Result<()> {
+        let now = chrono::Utc::now().to_rfc3339();
+        let db = self.db.lock().await;
+        let conn = db.connection();
+        conn.execute(
+            "UPDATE inbound_client_api_keys SET revoked = 1, updated_at = ?1 WHERE key_id = ?2",
+            params![now, key_id],
+        )?;
+        Ok(())
+    }
+
     /// Save a token record
     pub async fn save_token(&self, record: &TokenRecord) -> Result<()> {
         let db = self.db.lock().await;

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

@@ -17,8 +17,8 @@ pub use app_settings_repository::SqliteAppSettingsRepository;
 pub use credential_repository::SqliteCredentialRepository;
 pub use feature_set_repository::SqliteFeatureSetRepository;
 pub use inbound_client_repository::{
-    AuthorizationCode, InboundClient, InboundClientRepository, RegistrationType, TokenRecord,
-    TokenType,
+    ApiKeyAuth, AuthorizationCode, InboundApiKey, InboundClient, InboundClientRepository,
+    RegistrationType, TokenRecord, TokenType,
 };
 pub use inbound_mcp_client_repository::SqliteInboundMcpClientRepository;
 pub use installed_server_repository::SqliteInstalledServerRepository;