feat: GitHub OAuth one-click repo import

Secure server-side OAuth implementation for importing repos from GitHub.

Backend:
- Add github_connections table for secure token storage (RLS protected)
- OAuth flow: /github/connect, /github/callback, /github/status
- GitHubService for API interactions (repos, user info)
- Token never exposed to frontend, stored server-side only
- CSRF protection via state parameter

Frontend:
- GitHubRepoSelector modal for browsing/selecting repos
- GitHubCallbackPage for OAuth redirect handling
- useGitHubRepos hook for API integration
- Dashboard integration with 'Import from GitHub' button
- Free tier: 3 repo limit enforced in UI

Security:
- Separate OAuth scopes (user:email for login, repo for import)
- Token validation on each use
- Auto-cleanup on token revocation
- Supabase service_role for server-side token access

Author: DevanshuNEU

backend/.env.example

@@ -10,6 +10,13 @@ COHERE_API_KEY=your_cohere_api_key_here
 SUPABASE_URL=https://your-project.supabase.co
 SUPABASE_ANON_KEY=your_supabase_anon_key_here
 SUPABASE_JWT_SECRET=your_jwt_secret_here
+SUPABASE_SERVICE_ROLE_KEY=your_service_role_key_here
+
+# GitHub OAuth (for repo import feature)
+GITHUB_CLIENT_ID=your_github_oauth_app_client_id
+GITHUB_CLIENT_SECRET=your_github_oauth_app_client_secret
+GITHUB_REDIRECT_URI=http://localhost:3000/github/callback
+FRONTEND_URL=http://localhost:3000
 
 # Backend API
 BACKEND_API_URL=http://localhost:8000

backend/main.py

@@ -27,6 +27,7 @@
 from routes.api_keys import router as api_keys_router
 from routes.users import router as users_router
 from routes.search_v2 import router as search_v2_router
+from routes.github import router as github_router
 from routes.ws_playground import websocket_playground_index
 from routes.ws_repos import websocket_repo_indexing
 
@@ -92,6 +93,7 @@ async def dispatch(self, request: Request, call_next):
 app.include_router(api_keys_router, prefix=API_PREFIX)
 app.include_router(users_router, prefix=API_PREFIX)
 app.include_router(search_v2_router, prefix=API_PREFIX)
+app.include_router(github_router, prefix=API_PREFIX)
 
 # WebSocket endpoints (versioned)
 app.add_api_websocket_route(f"{API_PREFIX}/ws/index/{{repo_id}}", websocket_index)

backend/routes/github.py

@@ -0,0 +1,344 @@
+"""
+GitHub Integration Routes
+Handles OAuth flow and repository listing for one-click import
+
+SECURITY: Token exchange and storage happens server-side only.
+Frontend never sees the GitHub access token.
+"""
+import os
+import secrets
+import httpx
+from fastapi import APIRouter, HTTPException, Depends, Query
+from fastapi.responses import RedirectResponse
+from typing import Optional
+from pydantic import BaseModel
+from urllib.parse import urlencode
+
+from middleware.auth import require_auth, AuthContext
+from services.github import GitHubService
+from services.observability import logger
+
+
+router = APIRouter(prefix="/github", tags=["GitHub"])
+
+# GitHub OAuth config - load from env
+GITHUB_CLIENT_ID = os.getenv("GITHUB_CLIENT_ID")
+GITHUB_CLIENT_SECRET = os.getenv("GITHUB_CLIENT_SECRET")
+GITHUB_REDIRECT_URI = os.getenv("GITHUB_REDIRECT_URI", "http://localhost:3000/github/callback")
+FRONTEND_URL = os.getenv("FRONTEND_URL", "http://localhost:3000")
+
+
+class GitHubStatusResponse(BaseModel):
+    connected: bool
+    username: Optional[str] = None
+    avatar_url: Optional[str] = None
+
+
+class GitHubConnectResponse(BaseModel):
+    auth_url: str
+    state: str
+
+
+class GitHubCallbackRequest(BaseModel):
+    code: str
+    state: str
+
+
+class GitHubRepoResponse(BaseModel):
+    id: int
+    name: str
+    full_name: str
+    description: Optional[str]
+    html_url: str
+    clone_url: str
+    default_branch: str
+    private: bool
+    fork: bool
+    stars: int
+    language: Optional[str]
+    size_kb: int
+    owner: str
+    owner_avatar: str
+
+
+async def _get_github_connection(user_id: str) -> Optional[dict]:
+    """Get user's GitHub connection from database"""
+    try:
+        from services.supabase_service import get_supabase_service
+        db = get_supabase_service().client
+        result = db.table("github_connections").select("*").eq("user_id", user_id).execute()
+        return result.data[0] if result.data else None
+    except Exception as e:
+        logger.error("Failed to get GitHub connection", error=str(e), user_id=user_id)
+        return None
+
+
+async def _save_github_connection(
+    user_id: str,
+    access_token: str,
+    github_user_id: int,
+    github_username: str,
+    github_avatar_url: Optional[str],
+    scope: str
+) -> bool:
+    """Save or update GitHub connection in database"""
+    try:
+        from services.supabase_service import get_supabase_service
+        db = get_supabase_service().client
+        
+        data = {
+            "user_id": user_id,
+            "access_token": access_token,
+            "github_user_id": github_user_id,
+            "github_username": github_username,
+            "github_avatar_url": github_avatar_url,
+            "token_scope": scope,
+        }
+        
+        db.table("github_connections").upsert(data, on_conflict="user_id").execute()
+        return True
+    except Exception as e:
+        logger.error("Failed to save GitHub connection", error=str(e), user_id=user_id)
+        return False
+
+
+async def _delete_github_connection(user_id: str) -> bool:
+    """Remove GitHub connection"""
+    try:
+        from services.supabase_service import get_supabase_service
+        db = get_supabase_service().client
+        db.table("github_connections").delete().eq("user_id", user_id).execute()
+        return True
+    except Exception as e:
+        logger.error("Failed to delete GitHub connection", error=str(e), user_id=user_id)
+        return False
+
+
+async def _update_last_used(user_id: str) -> None:
+    """Update last_used_at timestamp"""
+    try:
+        from services.supabase_service import get_supabase_service
+        db = get_supabase_service().client
+        db.table("github_connections").update(
+            {"last_used_at": "now()"}
+        ).eq("user_id", user_id).execute()
+    except Exception:
+        pass
+
+
+@router.get("/status", response_model=GitHubStatusResponse)
+async def get_github_status(auth: AuthContext = Depends(require_auth)):
+    """Check if user has GitHub connected and token is valid"""
+    if not auth.user_id:
+        raise HTTPException(status_code=401, detail="User ID required")
+
+    connection = await _get_github_connection(auth.user_id)
+    if not connection:
+        return GitHubStatusResponse(connected=False)
+
+    # Verify token is still valid by making a test API call
+    try:
+        github = GitHubService(connection["access_token"])
+        is_valid = await github.validate_token()
+        
+        if not is_valid:
+            # Token expired or revoked, clean up
+            await _delete_github_connection(auth.user_id)
+            return GitHubStatusResponse(connected=False)
+
+        return GitHubStatusResponse(
+            connected=True,
+            username=connection.get("github_username"),
+            avatar_url=connection.get("github_avatar_url")
+        )
+    except Exception as e:
+        logger.warning("GitHub token validation failed", error=str(e))
+        return GitHubStatusResponse(connected=False)
+
+
+@router.get("/connect", response_model=GitHubConnectResponse)
+async def initiate_github_connect(auth: AuthContext = Depends(require_auth)):
+    """
+    Start GitHub OAuth flow for repo import
+    
+    Returns URL to redirect user to GitHub authorization page.
+    Frontend should redirect user to this URL.
+    """
+    if not auth.user_id:
+        raise HTTPException(status_code=401, detail="User ID required")
+
+    if not GITHUB_CLIENT_ID:
+        raise HTTPException(status_code=500, detail="GitHub OAuth not configured")
+
+    # Generate state token to prevent CSRF
+    # In production, store this in Redis/DB with expiry and user_id association
+    state = f"{auth.user_id}:{secrets.token_urlsafe(32)}"
+    
+    params = {
+        "client_id": GITHUB_CLIENT_ID,
+        "redirect_uri": GITHUB_REDIRECT_URI,
+        "scope": "repo",  # Full repo access for private repos
+        "state": state,
+        "allow_signup": "false",  # User should already have GitHub account
+    }
+    
+    auth_url = f"https://github.com/login/oauth/authorize?{urlencode(params)}"
+    
+    return GitHubConnectResponse(auth_url=auth_url, state=state)
+
+
+@router.post("/callback")
+async def github_oauth_callback(
+    request: GitHubCallbackRequest,
+    auth: AuthContext = Depends(require_auth)
+):
+    """
+    Handle GitHub OAuth callback
+    
+    Exchanges authorization code for access token and stores it.
+    Called by frontend after GitHub redirects back.
+    """
+    if not auth.user_id:
+        raise HTTPException(status_code=401, detail="User ID required")
+
+    if not GITHUB_CLIENT_ID or not GITHUB_CLIENT_SECRET:
+        raise HTTPException(status_code=500, detail="GitHub OAuth not configured")
+
+    # Verify state contains user_id (basic CSRF protection)
+    if not request.state.startswith(auth.user_id):
+        raise HTTPException(status_code=400, detail="Invalid state parameter")
+
+    # Exchange code for access token
+    async with httpx.AsyncClient() as client:
+        response = await client.post(
+            "https://github.com/login/oauth/access_token",
+            data={
+                "client_id": GITHUB_CLIENT_ID,
+                "client_secret": GITHUB_CLIENT_SECRET,
+                "code": request.code,
+                "redirect_uri": GITHUB_REDIRECT_URI,
+            },
+            headers={"Accept": "application/json"},
+            timeout=30.0
+        )
+        
+        if response.status_code != 200:
+            logger.error("GitHub token exchange failed", status=response.status_code)
+            raise HTTPException(status_code=400, detail="Failed to exchange code for token")
+        
+        token_data = response.json()
+        
+        if "error" in token_data:
+            logger.error("GitHub OAuth error", error=token_data.get("error_description"))
+            raise HTTPException(status_code=400, detail=token_data.get("error_description", "OAuth failed"))
+        
+        access_token = token_data.get("access_token")
+        scope = token_data.get("scope", "")
+        
+        if not access_token:
+            raise HTTPException(status_code=400, detail="No access token received")
+
+    # Get GitHub user info
+    github = GitHubService(access_token)
+    user_info = await github.get_user()
+    
+    if not user_info:
+        raise HTTPException(status_code=400, detail="Failed to get GitHub user info")
+
+    # Save connection to database
+    saved = await _save_github_connection(
+        user_id=auth.user_id,
+        access_token=access_token,
+        github_user_id=user_info.id,
+        github_username=user_info.login,
+        github_avatar_url=user_info.avatar_url,
+        scope=scope
+    )
+    
+    if not saved:
+        raise HTTPException(status_code=500, detail="Failed to save GitHub connection")
+
+    logger.info("GitHub connected successfully", user_id=auth.user_id, github_user=user_info.login)
+    
+    return {
+        "success": True,
+        "username": user_info.login,
+        "avatar_url": user_info.avatar_url
+    }
+
+
+@router.delete("/disconnect")
+async def disconnect_github(auth: AuthContext = Depends(require_auth)):
+    """Remove GitHub connection"""
+    if not auth.user_id:
+        raise HTTPException(status_code=401, detail="User ID required")
+
+    deleted = await _delete_github_connection(auth.user_id)
+    return {"success": deleted}
+
+
+@router.get("/repos", response_model=list[GitHubRepoResponse])
+async def list_github_repos(
+    auth: AuthContext = Depends(require_auth),
+    include_forks: bool = False,
+    page: int = Query(default=1, ge=1),
+    per_page: int = Query(default=50, ge=1, le=100)
+):
+    """
+    List user's GitHub repositories for import selection
+    
+    Returns repos sorted by last updated, excludes forks by default.
+    Includes both personal repos and org repos user has access to.
+    """
+    if not auth.user_id:
+        raise HTTPException(status_code=401, detail="User ID required")
+
+    connection = await _get_github_connection(auth.user_id)
+    if not connection:
+        raise HTTPException(
+            status_code=400,
+            detail="GitHub not connected. Please connect your GitHub account first."
+        )
+
+    try:
+        github = GitHubService(connection["access_token"])
+        repos = await github.get_repos(
+            include_forks=include_forks,
+            per_page=per_page,
+            page=page
+        )
+
+        # Update last used timestamp
+        await _update_last_used(auth.user_id)
+
+        return [
+            GitHubRepoResponse(
+                id=repo.id,
+                name=repo.name,
+                full_name=repo.full_name,
+                description=repo.description,
+                html_url=repo.html_url,
+                clone_url=repo.clone_url,
+                default_branch=repo.default_branch,
+                private=repo.private,
+                fork=repo.fork,
+                stars=repo.stargazers_count,
+                language=repo.language,
+                size_kb=repo.size,
+                owner=repo.owner_login,
+                owner_avatar=repo.owner_avatar
+            )
+            for repo in repos
+        ]
+    except Exception as e:
+        logger.error("Failed to fetch GitHub repos", error=str(e), user_id=auth.user_id)
+        
+        # Check if token was revoked
+        if "401" in str(e) or "Bad credentials" in str(e):
+            await _delete_github_connection(auth.user_id)
+            raise HTTPException(
+                status_code=401,
+                detail="GitHub access revoked. Please reconnect your GitHub account."
+            )
+        
+        raise HTTPException(status_code=500, detail=f"Failed to fetch repositories: {str(e)}")