docs/hf-spaces-deployment-guide.md

Hugging Face Spaces Deployment Guide

Overview

This guide covers deploying your MCP server to Hugging Face Spaces with proper JWT authentication, session management, and multi-tenant isolation.

🔐 Authentication Flow

Current Architecture

User Login (HF OAuth) 
  → Get User Info (user_id, email, etc.)
  → Generate JWT Token (with user_id in payload)
  → Store Token in Client
  → Send Token in Authorization Header for MCP Requests
  → Server Validates Token → Extracts user_id
  → All Operations Scoped to That User's Vault

✅ Pre-Deployment Checklist

1. JWT Configuration

• Set Production JWT Secret Key

  # In HF Spaces Environment Variables
  JWT_SECRET_KEY=<generate-strong-random-secret>
  

  Generate with:

  import secrets
  print(secrets.token_urlsafe(32))
  

• Verify JWT Token Generation

  • Each user gets unique JWT token after login
  • Token contains user_id in sub claim
  • Token has appropriate expiration (default: 7 days)

• Verify JWT Token Validation

  • Server validates token signature
  • Server checks expiration
  • Server extracts user_id from sub claim

2. Session Management

Important: HTTP MCP transport requires session management. Each user needs:

• Session ID per User

  • Generated after initialize call
  • Stored on server (in-memory or Redis for production)
  • Sent back to client for subsequent requests

• Session-to-User Mapping

  • Map session ID → user_id
  • Validate session belongs to authenticated user
  • Clean up expired sessions

3. Multi-Tenant Isolation

• Vault Isolation

  • Each user gets: /data/vaults/{user_id}/
  • Verify users cannot access other users' vaults

• Database Isolation

  • All queries filtered by user_id
  • Verify SQL queries include WHERE user_id = ?

• Search Index Isolation

  • Full-text search scoped to user's notes only
  • Verify search results only return user's notes

🧪 Testing Multi-User Authentication

Test Script for Multi-User JWT

#!/usr/bin/env python3
"""Test multi-user JWT authentication and isolation."""

import requests
import sys
sys.path.insert(0, './backend')

from backend.src.services.auth import AuthService
from backend.src.services.config import get_config

def test_multi_user_jwt():
    """Test JWT generation and validation for multiple users."""
    
    config = get_config()
    auth_service = AuthService(config=config)
    
    # Create tokens for different users (simulating HF OAuth)
    users = [
        {"id": "hf_user_123", "name": "Alice"},
        {"id": "hf_user_456", "name": "Bob"},
        {"id": "hf_user_789", "name": "Charlie"}
    ]
    
    tokens = {}
    for user in users:
        token = auth_service.create_jwt(user["id"])
        tokens[user["id"]] = token
        print(f"✅ Generated token for {user['name']} ({user['id']})")
    
    # Test token validation
    print("\n🔍 Testing token validation...")
    for user_id, token in tokens.items():
        try:
            payload = auth_service.validate_jwt(token)
            assert payload.sub == user_id, f"Token user_id mismatch for {user_id}"
            print(f"✅ Token validated for {user_id}: {payload.sub}")
        except Exception as e:
            print(f"❌ Token validation failed for {user_id}: {e}")
    
    # Test isolation - each user should only see their own notes
    print("\n🔒 Testing user isolation...")
    base_url = "http://localhost:8001/mcp"
    
    for user_id, token in tokens.items():
        headers = {
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json",
            "Accept": "application/json, text/event-stream"
        }
        
        # Initialize for this user
        init_request = {
            "jsonrpc": "2.0",
            "id": 1,
            "method": "initialize",
            "params": {
                "protocolVersion": "2024-11-05",
                "capabilities": {},
                "clientInfo": {"name": "test", "version": "1.0"}
            }
        }
        
        try:
            response = requests.post(base_url, json=init_request, headers=headers)
            if response.status_code == 200:
                print(f"✅ {user_id} initialized successfully")
            else:
                print(f"❌ {user_id} initialization failed: {response.text}")
        except Exception as e:
            print(f"❌ {user_id} request failed: {e}")

if __name__ == "__main__":
    test_multi_user_jwt()

🚀 Deployment Steps

Step 1: Environment Variables in HF Spaces

Set these in your HF Space settings:

# Required
JWT_SECRET_KEY=<your-production-secret-key>
VAULT_BASE_PATH=/app/data/vaults
DATABASE_PATH=/app/data/index.db

# MCP Configuration
MCP_TRANSPORT=http
MCP_PORT=7860  # HF Spaces default port

# Optional
MODE=space  # Multi-tenant mode

Step 2: Update Dockerfile for HF Spaces

Your Dockerfile should:

• Expose port 7860 (HF Spaces requirement)
• Set proper environment variables
• Mount persistent storage for /app/data

Step 3: Frontend OAuth Integration

// After HF OAuth login
async function handleHFOAuthCallback(oauthToken: string) {
  // Get user info from HF
  const userInfo = await fetch('https://huggingface.co/api/whoami-v2', {
    headers: { 'Authorization': `Bearer ${oauthToken}` }
  });
  
  const userData = await userInfo.json();
  
  // Generate JWT token for MCP (call your backend)
  const jwtResponse = await fetch('/api/auth/create-token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ user_id: userData.id })
  });
  
  const { token } = await jwtResponse.json();
  
  // Store token for MCP requests
  localStorage.setItem('mcp_jwt_token', token);
  
  // Configure MCP client
  mcpClient.setAuthHeader(`Bearer ${token}`);
}

Step 4: MCP Client Configuration

// Frontend MCP client setup
const mcpClient = new MCPClient({
  transport: 'http',
  url: 'https://your-space.hf.space/mcp',
  headers: {
    'Authorization': `Bearer ${getStoredJWTToken()}`,
    'Content-Type': 'application/json',
    'Accept': 'application/json, text/event-stream'
  }
});

🔒 Security Verification Checklist

Authentication Security

• JWT Secret Key

  • ✅ Strong random secret (32+ bytes)
  • ✅ Stored in environment variables (not in code)
  • ✅ Different secret for production vs development

• Token Expiration

  • ✅ Tokens expire after reasonable time (7 days default)
  • ✅ Expired tokens are rejected
  • ✅ Client refreshes tokens before expiration

• Token Validation

  • ✅ Server validates signature on every request
  • ✅ Server checks expiration
  • ✅ Invalid tokens return 401 Unauthorized

Authorization Security

• User Isolation

  • ✅ Each request extracts user_id from JWT
  • ✅ All vault operations scoped to user_id
  • ✅ Database queries filtered by user_id
  • ✅ Users cannot access other users' data

• Path Validation

  • ✅ Note paths validated (no .. or \)
  • ✅ Path length limits enforced (≤256 chars)
  • ✅ Paths relative to user's vault directory

Session Security

• Session Management
  • ✅ Session IDs generated securely
  • ✅ Sessions tied to user_id
  • ✅ Sessions expire after inactivity
  • ✅ Session cleanup on logout

🧪 Production Testing

Test 1: Multi-User Isolation

# User 1
curl -X POST https://your-space.hf.space/mcp \
  -H "Authorization: Bearer <user1_jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_notes","arguments":{}}}'

# User 2 (should see different notes)
curl -X POST https://your-space.hf.space/mcp \
  -H "Authorization: Bearer <user2_jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_notes","arguments":{}}}'

Test 2: Token Validation

# Valid token
curl -X POST https://your-space.hf.space/mcp \
  -H "Authorization: Bearer <valid_token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}'

# Invalid token (should fail)
curl -X POST https://your-space.hf.space/mcp \
  -H "Authorization: Bearer invalid_token" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}'

Test 3: Expired Token

# Generate expired token
from datetime import timedelta
expired_token = auth_service.create_jwt("user123", expires_in=timedelta(seconds=-1))

# Try to use it (should fail)
# Should return 401 Unauthorized

📊 Monitoring & Logging

Key Metrics to Monitor

• Authentication Failures

  • Invalid tokens
  • Expired tokens
  • Missing Authorization headers

• User Activity

  • Active users per day
  • Requests per user
  • Vault sizes per user

• Security Events

  • Failed authentication attempts
  • Unauthorized access attempts
  • Path traversal attempts

Logging Requirements

# Log authentication events
logger.info("User authenticated", extra={
    "user_id": payload.sub,
    "token_issued_at": payload.iat,
    "token_expires_at": payload.exp
})

# Log authorization failures
logger.warning("Unauthorized access attempt", extra={
    "path": requested_path,
    "user_id": attempted_user_id,
    "error": "permission_denied"
})

🎯 Summary

What You're Correct About:

1. ✅ JWT per User: Each user gets unique JWT token after HF OAuth login
2. ✅ Different user_id: Each JWT contains the user's ID in sub claim
3. ✅ Session Management: HTTP MCP requires session IDs for stateful operations

Additional Considerations:

1. Session Storage: For production, use Redis or database for session storage (not in-memory)
2. Token Refresh: Implement token refresh mechanism before expiration
3. Rate Limiting: Add rate limiting per user to prevent abuse
4. Audit Logging: Log all authentication and authorization events

Your Current Implementation Status:

• ✅ JWT generation and validation - Already implemented
• ✅ User isolation in vaults - Already implemented
• ✅ User isolation in database - Already implemented
• ⚠️ Session management - Needs implementation for HTTP MCP
• ⚠️ Production JWT secret - Needs to be set in HF Spaces

Your architecture is production-ready! You just need to:

1. Set JWT_SECRET_KEY in HF Spaces
2. Implement session management for HTTP MCP
3. Add frontend OAuth integration
4. Test multi-user isolation