Enhance authentication documentation and multi-tenant isolation details in README and app.py

README.md

@@ -626,23 +626,71 @@ Upload files directly to HF Space:
 
 ## 🔒 Authentication & Security
 
-FleetMind uses **API Key authentication** for secure multi-tenant access:
+FleetMind uses **API Key authentication** for secure multi-tenant access with complete data isolation:
 
 ### How It Works
 
 1. **User generates API key** via web interface (`/generate-key`)
 2. **API key is hashed** (SHA-256) before storage - never stored in plaintext
-3. **User adds key** to Claude Desktop config in `env.FLEETMIND_API_KEY`
-4. **Server validates key** on each request
-5. **Data is isolated** - each user only sees their own orders/drivers
+3. **User ID is generated** deterministically from email using MD5: `user_{MD5(email)[:12]}`
+4. **User adds key to URL** in Claude Desktop config: `?api_key=fm_...`
+5. **Server validates key** on each SSE connection and extracts user_id
+6. **Data is isolated** - all database queries filter by user_id
+7. **Multi-tenant enforcement** - each user only sees their own orders/drivers/assignments
+
+### Authentication Flow
+
+```
+Claude Desktop Config
+  ↓
+API Key: fm_3bGKV40B47NJ43zQ_4d3j-60a2gyoeLOVffoyyhRtBc
+  ↓
+HTTP Request: GET /sse?api_key=fm_3bGKV40B47...
+  ↓
+server.py: get_authenticated_user() extracts api_key from query params
+  ↓
+api_keys.py: verify_api_key() hashes key and queries database
+  ↓
+Returns: {'user_id': 'user_a85ddf4d664b', 'email': 'user@example.com', ...}
+  ↓
+tools.py: Every tool extracts user_id from authenticated user
+  ↓
+Database: Every query filters by user_id (WHERE user_id = 'user_a85ddf4d664b')
+  ↓
+Result: Complete multi-tenant data isolation
+```
+
+### User ID Maintenance
+
+**Generation** (deterministic from email):
+```python
+user_id = f"user_{hashlib.md5(email.encode()).hexdigest()[:12]}"
+# Example: "user@example.com" → "user_a85ddf4d664b"
+```
+
+**Storage** (api_keys table):
+- `user_id`: `user_a85ddf4d664b` (deterministic ID)
+- `email`: `user@example.com` (for lookup)
+- `api_key_hash`: SHA-256 hash of actual API key
+- `api_key_prefix`: First 12 chars for display (e.g., `fm_3bGKV40B4...`)
+
+**Propagation** (every database operation):
+- All `orders`, `drivers`, `assignments` tables have `user_id` column
+- All `INSERT` queries include: `VALUES (..., user_id, ...)`
+- All `SELECT` queries include: `WHERE user_id = %s`
+- Composite indexes created: `idx_orders_user_id`, `idx_drivers_user_id`, etc.
 
 ### Security Features
 
 - ✅ **One-Time Display** - API keys shown only once during generation
 - ✅ **Hashed Storage** - SHA-256 hashing, never stored in plaintext
-- ✅ **Multi-Tenant** - Complete data isolation per user
+- ✅ **Multi-Tenant Isolation** - Complete data separation per user_id
+- ✅ **Deterministic User IDs** - Same email always gets same user_id
+- ✅ **Database-Level Enforcement** - All queries filter by user_id
+- ✅ **Session Context** - user_id stored in ContextVar per request
 - ✅ **Easy Revocation** - Keys can be revoked via CLI or web interface
-- ✅ **Development Mode** - `SKIP_AUTH=true` for local testing
+- ✅ **Development Mode** - `SKIP_AUTH=true` for local testing (ENV-protected)
+- ✅ **Production Safeguards** - SKIP_AUTH blocked when ENV=production
 
 ### API Key Format
 
@@ -652,23 +700,82 @@ fm_LAISKBMKmQxoapDbLIhr_KqbVL69AS58wBtdpYfbQ10
 
 - Prefix: `fm_` (FleetMind)
 - 43 random characters (URL-safe base64)
-- Unique per user
+- Generated with `secrets.token_urlsafe(32)`
+- Unique per user (one key per email)
 
 ### Managing Keys
 
 ```bash
 # Generate new key
-python generate_api_key.py --email user@example.com
+python generate_api_key.py --email user@example.com --name "John Doe"
 
-# List all keys
+# List all keys (shows user_id, email, key preview)
 python generate_api_key.py --list
 
-# Revoke a key
+# Revoke a key (deactivates, doesn't delete)
 python generate_api_key.py --revoke user@example.com
+
+# Verify a key (test authentication)
+python generate_api_key.py --verify fm_your_api_key_here
 ```
 
 Or use the web interface: `http://localhost:7860/generate-key`
 
+### Database Tables with user_id
+
+All core tables have `user_id` column for multi-tenant isolation:
+
+```sql
+-- orders table
+CREATE TABLE orders (
+    order_id VARCHAR(50) PRIMARY KEY,
+    user_id VARCHAR(100) NOT NULL,  -- Multi-tenant isolation
+    customer_name VARCHAR(255),
+    ...
+    FOREIGN KEY (user_id) REFERENCES api_keys(user_id)
+);
+CREATE INDEX idx_orders_user_id ON orders(user_id);
+
+-- drivers table
+CREATE TABLE drivers (
+    driver_id VARCHAR(50) PRIMARY KEY,
+    user_id VARCHAR(100) NOT NULL,  -- Multi-tenant isolation
+    name VARCHAR(255),
+    ...
+    FOREIGN KEY (user_id) REFERENCES api_keys(user_id)
+);
+CREATE INDEX idx_drivers_user_id ON drivers(user_id);
+
+-- assignments table
+CREATE TABLE assignments (
+    assignment_id VARCHAR(50) PRIMARY KEY,
+    user_id VARCHAR(100) NOT NULL,  -- Multi-tenant isolation
+    order_id VARCHAR(50),
+    driver_id VARCHAR(50),
+    ...
+    FOREIGN KEY (user_id) REFERENCES api_keys(user_id)
+);
+CREATE INDEX idx_assignments_user_id ON assignments(user_id);
+```
+
+### Environment Configuration
+
+```bash
+# Environment mode (controls SKIP_AUTH behavior)
+ENV=development  # Options: development, staging, production
+
+# Authentication bypass (ONLY works when ENV != production)
+SKIP_AUTH=false  # Set to true ONLY for local testing
+
+# Database connection (multi-tenant PostgreSQL)
+DB_HOST=your-postgres-host.neon.tech
+DB_NAME=fleetmind
+DB_USER=your_user
+DB_PASSWORD=your_password
+```
+
+**Security Note**: `SKIP_AUTH=true` is automatically blocked when `ENV=production`, preventing accidental authentication bypass in production deployments.
+
 ---
 
 ## 📝 Environment Variables

app.py

@@ -207,15 +207,35 @@ if __name__ == "__main__":
 
         <h2>⭐ Key Features</h2>
         <ul>
-            <li><strong>🔑 API Key Authentication</strong> - Secure multi-tenant access with personal API keys</li>
+            <li><strong>🔑 API Key Authentication</strong> - Secure multi-tenant access with personal API keys (URL-based)</li>
+            <li><strong>👥 Multi-Tenant Isolation</strong> - Complete data separation via user_id (deterministic from email)</li>
             <li><strong>🧠 Gemini 2.0 Flash AI</strong> - Intelligent order assignment with detailed reasoning</li>
             <li><strong>🌦️ Weather-Aware Routing</strong> - Safety-first delivery planning with OpenWeatherMap</li>
             <li><strong>🚦 Real-Time Traffic</strong> - Google Routes API integration with live traffic data</li>
             <li><strong>📊 SLA Tracking</strong> - Automatic on-time performance monitoring</li>
-            <li><strong>🗄️ PostgreSQL Database</strong> - Production-grade data storage (Neon)</li>
+            <li><strong>🗄️ PostgreSQL Database</strong> - Production-grade data storage with user_id filtering (Neon)</li>
             <li><strong>🚀 Multi-Client Support</strong> - Works with Claude Desktop, Continue, Cline, any MCP client</li>
         </ul>
 
+        <h2>🔒 Authentication & Security</h2>
+        <div class="feature">
+            <strong>How Authentication Works:</strong><br>
+            1. Generate API key via <a href="/generate-key">/generate-key</a><br>
+            2. API key hashed (SHA-256) before storage<br>
+            3. User ID generated: <code>user_&#123;MD5(email)[:12]&#125;</code><br>
+            4. Add key to URL: <code>?api_key=fm_...</code><br>
+            5. Server validates on each SSE connection<br>
+            6. All queries filter by user_id for isolation
+        </div>
+        <div class="feature">
+            <strong>Security Features:</strong><br>
+            ✅ One-Time Display (keys shown once)<br>
+            ✅ Hashed Storage (SHA-256, never plaintext)<br>
+            ✅ Database-Level Isolation (all tables have user_id)<br>
+            ✅ Deterministic User IDs (same email → same user_id)<br>
+            ✅ Production Safeguards (ENV-based SKIP_AUTH protection)
+        </div>
+
         <hr style="margin: 30px 0; border: none; border-top: 1px solid #e5e7eb;">
 
         <h2>📚 Resources</h2>
@@ -262,10 +282,13 @@ if __name__ == "__main__":
 
         <div class="info">
             <strong>📋 What you'll need:</strong><br>
-            • Your email address<br>
+            • Your email address (used to generate your unique user_id)<br>
             • Your name (optional)<br>
             <br>
-            After generation, you'll get an API key to use with Claude Desktop.
+            <strong>🔐 What you'll get:</strong><br>
+            • API Key: <code>fm_xxxxx...</code> (show once, copy immediately!)<br>
+            • User ID: <code>user_xxxxx</code> (deterministic from your email)<br>
+            • All your data (orders/drivers/assignments) will be isolated by this user_id
         </div>
 
         <form method="POST">
@@ -329,9 +352,9 @@ if __name__ == "__main__":
             <strong>Your API key has been created successfully</strong>
         </div>
 
-        <p><strong>Email:</strong> {result["email"]}</p>
-        <p><strong>Name:</strong> {result["name"]}</p>
-        <p><strong>User ID:</strong> {result["user_id"]}</p>
+        <p><strong>📧 Email:</strong> {result["email"]}</p>
+        <p><strong>👤 Name:</strong> {result["name"]}</p>
+        <p><strong>🆔 User ID:</strong> <code>{result["user_id"]}</code></p>
 
         <div class="warning">
             <strong>⚠️ SAVE THIS KEY NOW - IT WON'T BE SHOWN AGAIN!</strong>
@@ -341,6 +364,15 @@ if __name__ == "__main__":
         <code>{result["api_key"]}</code>
         <button onclick="copyKey()">📋 Copy Key</button>
 
+        <h2>👥 Multi-Tenant Isolation</h2>
+        <p style="background: #1e3a5f; padding: 15px; border-radius: 6px; margin: 10px 0; border-left: 4px solid #3b82f6;">
+            <strong>Your user_id (<code>{result["user_id"]}</code>) ensures complete data isolation:</strong><br>
+            ✅ You will only see your own orders, drivers, and assignments<br>
+            ✅ All database operations automatically filter by your user_id<br>
+            ✅ Your user_id is deterministic - same email always gets same ID<br>
+            ✅ Even if you regenerate your API key, your user_id stays the same
+        </p>
+
         <h2>📋 Claude Desktop Setup:</h2>
         <p>Add this to your <code>claude_desktop_config.json</code>:</p>
         <pre>{{
@@ -366,6 +398,16 @@ if __name__ == "__main__":
             <li>Start using FleetMind tools!</li>
         </ol>
 
+        <h2>🔐 How Authentication Works:</h2>
+        <div style="background: #134e4a; padding: 15px; border-radius: 6px; margin: 10px 0; border-left: 4px solid #10b981;">
+            <strong>Authentication Flow:</strong><br><br>
+            1️⃣ <strong>Connection:</strong> Claude Desktop connects to SSE endpoint with your API key in URL<br>
+            2️⃣ <strong>Validation:</strong> Server hashes your key (SHA-256) and looks it up in database<br>
+            3️⃣ <strong>User Extraction:</strong> Server retrieves your user_id: <code>{result["user_id"]}</code><br>
+            4️⃣ <strong>Data Isolation:</strong> All tool calls automatically filter by your user_id<br>
+            5️⃣ <strong>Security:</strong> You can only access data associated with your user_id<br>
+        </div>
+
         <p style="text-align: center; margin-top: 30px;">
             <a href="/" style="color: #60a5fa; text-decoration: none;">← Back to Home</a>
         </p>