feat: add callback api

app/api/server.py

@@ -37,8 +37,14 @@ _PUBLIC_API_PREFIXES = (
     "/api/v1/url-shortener/",
 )
 
+# GET-only paths that must not require authentication: Google redirects the
+# user's browser here after authorization, and a redirect cannot attach the API key.
+_PUBLIC_GET_PATHS = frozenset({"/api/v1/google/oauth/callback"})
 
-def _is_public_path(path: str) -> bool:
+
+def _is_public_path(path: str, method: str = "GET") -> bool:
+    if path in _PUBLIC_GET_PATHS and method == "GET":
+        return True
     return path.startswith(_PUBLIC_API_PREFIXES)
 
 
@@ -217,7 +223,7 @@ def create_application() -> FastAPI:
     @app.middleware("http")
     async def auth_middleware(request: Request, call_next):
         path = request.url.path
-        if path.startswith("/api/v1/") and not _is_public_path(path):
+        if path.startswith("/api/v1/") and not _is_public_path(path, request.method):
             auth_header = request.headers.get("Authorization", "")
             if not auth_header.startswith("Bearer "):
                 from starlette.responses import JSONResponse

app/api/v1/google_oauth.py

@@ -10,6 +10,7 @@ from app.models.schemas import (
     GoogleOAuthAuthUrlRequest,
     GoogleOAuthAuthUrlResponse,
     GoogleOAuthCallbackRequest,
+    GoogleOAuthCallbackResponse,
     GoogleOAuthRefreshRequest,
     GoogleOAuthTokenResponse,
     GoogleOAuthVerifyRequest,
@@ -134,6 +135,59 @@ async def oauth_callback(
     )
 
 
+@router.get("/callback", response_model=GoogleOAuthCallbackResponse,
+            summary="Capture the data Google returns after the user authorizes (browser redirect)")
+async def oauth_callback_redirect(
+    state: Optional[str] = None,
+    code: Optional[str] = None,
+    error: Optional[str] = None,
+    error_description: Optional[str] = None,
+    scope: Optional[str] = None,
+    authuser: Optional[str] = None,
+    prompt: Optional[str] = None,
+):
+    """Handle the browser redirect Google sends to ``redirect_uri``.
+
+    Captures the data Google returns after authentication — ``code`` on
+    success, or ``error``/``error_description`` when access is denied — and
+    returns it so the client can exchange the code via ``POST /callback``.
+    """
+    start = time.perf_counter()
+
+    if not state:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Missing 'state' parameter in the OAuth callback.",
+        )
+    if not _verify_state(state):
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Invalid or expired state token. Possible CSRF attack.",
+        )
+
+    _logger.info(
+        "Google OAuth callback captured data for state '%s...' (%.2fms)",
+        state[:12],
+        (time.perf_counter() - start) * 1000,
+    )
+    return GoogleOAuthCallbackResponse(
+        success=error is None,
+        state=state,
+        code=code,
+        error=error,
+        error_description=error_description,
+        scope=scope,
+        authuser=authuser,
+        prompt=prompt,
+        message=(
+            "Authorization successful. Exchange the code via POST /google/oauth/callback."
+            if error is None
+            else f"Authorization failed: {error}."
+            + (f" {error_description}" if error_description else "")
+        ),
+    )
+
+
 @router.post("/refresh", response_model=GoogleOAuthTokenResponse,
              summary="Refresh an expired access token (Step 3)")
 async def refresh_token(

app/models/schemas.py

@@ -956,6 +956,20 @@ class GoogleOAuthVerifyResponse(BaseModel):
     error: Optional[str] = None
 
 
+class GoogleOAuthCallbackResponse(BaseModel):
+    """Response returned by the browser-redirect callback (GET /callback)."""
+
+    success: bool = Field(..., description="Whether authorization succeeded (no error from Google)")
+    state: Optional[str] = Field(None, description="CSRF state token echoed back by Google")
+    code: Optional[str] = Field(None, description="Authorization code to exchange via POST /callback")
+    error: Optional[str] = Field(None, description="OAuth error code (e.g. access_denied) when the user denied access")
+    error_description: Optional[str] = Field(None, description="Human-readable error description from Google")
+    scope: Optional[str] = Field(None, description="Space-separated scope granted by the user")
+    authuser: Optional[str] = Field(None, description="Google account index echoed by Google")
+    prompt: Optional[str] = Field(None, description="Prompt mode echoed by Google")
+    message: Optional[str] = Field(None, description="Developer-friendly summary of the callback outcome")
+
+
 # ---------------------------------------------------------------------------
 # Google per-API scope catalog (single endpoint to view/set current scopes)
 # ---------------------------------------------------------------------------