fix: review findings -- unreachable user check, UUID validation, key preview suffix

1. auth.py: 'no linked user' check moved INTO _validate_api_key() where
   it can actually fire. Previously it was in _authenticate's error block
   which only ran when _validate_api_key returned None (meaning the key
   wasn't found at all, so user_id was never checked).

2. api_keys.py: key_id parameter changed from str to UUID. FastAPI now
   returns 422 for malformed UUIDs before hitting the DB. Added return
   type annotations (Dict[str, Any]) to list and revoke routes.

3. rate_limiter.py: key_preview now uses persisted key_suffix (last 8
   chars of raw key) instead of SHA-256 hash suffix. Users see
   'ci_...xYz12345' matching their actual key, not hash gibberish.

4. 004_api_keys.sql: added key_suffix column.

Skipped: async conversion of service methods (Supabase client is sync;
all other APIKeyManager methods are sync, would be inconsistent).

Dev: run ALTER TABLE api_keys ADD COLUMN key_suffix text; in Supabase.

392 tests pass.

Author: DevanshuNEU

backend/middleware/auth.py

@@ -133,11 +133,21 @@ def _validate_api_key(token: str) -> Optional[AuthContext]:
         except Exception:
             pass  # Non-critical; don't fail auth over timestamp update
 
+        # Reject keys with no linked user at the auth layer
+        # so routes get a clear 401 instead of silently passing with user_id=None
+        if not key_data.get("user_id"):
+            raise HTTPException(
+                status_code=401,
+                detail="API key has no linked user. Contact admin."
+            )
+
         return AuthContext(
             api_key_name=key_data.get("name"),
             user_id=key_data.get("user_id"),
             tier=key_data.get("tier", "free")
         )
+    except HTTPException:
+        raise
     except Exception:
         return None
 
@@ -173,8 +183,6 @@ def _authenticate(token: str) -> AuthContext:
                 detail = "API key not found. Check that the key is correct."
             elif not result.data[0].get("active"):
                 detail = "API key has been revoked."
-            elif not result.data[0].get("user_id"):
-                detail = "API key has no linked user. Contact admin."
             else:
                 detail = "API key validation failed."
         except Exception:

backend/routes/api_keys.py

@@ -1,4 +1,7 @@
 """API key management and metrics routes."""
+from typing import Any, Dict
+from uuid import UUID
+
 from fastapi import APIRouter, HTTPException, Depends
 from pydantic import BaseModel
 
@@ -115,7 +118,7 @@ async def generate_api_key(
 @router.get("/keys")
 async def list_api_keys(
     auth: AuthContext = Depends(require_auth)
-):
+) -> Dict[str, Any]:
     """List all API keys for the authenticated user."""
     if not auth.user_id:
         raise HTTPException(status_code=401, detail="User ID required")
@@ -131,15 +134,15 @@ async def list_api_keys(
 
 @router.delete("/keys/{key_id}")
 async def revoke_api_key(
-    key_id: str,
+    key_id: UUID,
     auth: AuthContext = Depends(require_auth)
-):
+) -> Dict[str, Any]:
     """Revoke an API key by ID. Soft-deletes (sets active=false)."""
     if not auth.user_id:
         raise HTTPException(status_code=401, detail="User ID required")
 
     try:
-        success = api_key_manager.revoke_key_by_id(key_id, auth.user_id)
+        success = api_key_manager.revoke_key_by_id(str(key_id), auth.user_id)
         if not success:
             raise HTTPException(
                 status_code=404,

backend/services/rate_limiter.py

@@ -180,9 +180,12 @@ def __init__(self, supabase_client):
     def generate_key(self, name: str, tier: str = 'free', user_id: Optional[str] = None) -> Dict:
         """Generate a new API key. Returns dict with raw key + metadata."""
         key = f"ci_{secrets.token_urlsafe(32)}"
+        # Persist last 8 chars of raw key for display (ci_...xYz12345)
+        suffix = key[-8:]
 
         result = self.db.table("api_keys").insert({
             "key_hash": hashlib.sha256(key.encode()).hexdigest(),
+            "key_suffix": suffix,
             "name": name,
             "tier": tier,
             "user_id": user_id,
@@ -230,18 +233,18 @@ def revoke_key_by_id(self, key_id: str, user_id: str) -> bool:
     def list_keys(self, user_id: str) -> list:
         """List all API keys for a user. Returns masked keys (no raw values)."""
         result = self.db.table("api_keys").select(
-            "id, name, tier, active, created_at, last_used_at, key_hash"
+            "id, name, tier, active, created_at, last_used_at, key_suffix"
         ).eq("user_id", user_id).order("created_at", desc=True).execute()
         keys = []
         for row in result.data:
-            h = row.get("key_hash", "")
+            suffix = row.get("key_suffix", "")
             keys.append({
                 "id": row["id"],
                 "name": row["name"],
                 "tier": row["tier"],
                 "active": row["active"],
                 "created_at": row["created_at"],
                 "last_used_at": row.get("last_used_at"),
-                "key_preview": f"ci_...{h[-8:]}" if h else "ci_...",
+                "key_preview": f"ci_...{suffix}" if suffix else "ci_...",
             })
         return keys

supabase/migrations/004_api_keys.sql

@@ -13,6 +13,7 @@ CREATE TABLE IF NOT EXISTS api_keys (
   user_id uuid REFERENCES auth.users(id) ON DELETE CASCADE,
   name text NOT NULL,
   key_hash text NOT NULL UNIQUE,
+  key_suffix text,  -- last 8 chars of raw key for masked display (ci_...xYz12345)
   tier text DEFAULT 'free' CHECK (tier IN ('free', 'pro', 'enterprise')),
   active boolean DEFAULT true,
   created_at timestamptz DEFAULT now(),