feat: warning

app/api/v1/google_oauth.py

@@ -55,6 +55,42 @@ def _http_error(exc: GoogleOAuthError) -> HTTPException:
     return HTTPException(status_code=exc.status_code, detail=exc.message)
 
 
+# Google's basic OpenID profile scopes. A "Testing" consent screen does NOT
+# apply the 7-day refresh-token expiry when only these scopes are requested.
+_BASIC_PROFILE_SCOPES = frozenset({
+    "openid",
+    "email",
+    "profile",
+    "https://www.googleapis.com/auth/userinfo.email",
+    "https://www.googleapis.com/auth/userinfo.profile",
+})
+
+
+def _refresh_token_warning(*, access_type: Optional[str], scope: str) -> Optional[str]:
+    """Return a user-facing warning about the refresh token this flow will issue.
+
+    Mirrors Google's documented refresh-token expiration rules:
+    https://developers.google.com/identity/protocols/oauth2#expiration
+    """
+    if access_type != "offline":
+        return (
+            "No refresh token will be issued because access_type is not 'offline'. "
+            "Set access_type to 'offline' to receive a long-lived refresh token "
+            "(issued only on the user's first authorization)."
+        )
+
+    requested_scopes = {s.strip() for s in scope.split() if s.strip()}
+    testing_note = ""
+    if not requested_scopes.issubset(_BASIC_PROFILE_SCOPES):
+        testing_note = (
+            " However, it expires after 7 days if the OAuth consent screen is in "
+            "'Testing' publishing status."
+        )
+    return (
+        "The refresh token is long-lived and does not expire on its own."
+    ) + testing_note
+
+
 @router.post("/auth-url", response_model=GoogleOAuthAuthUrlResponse,
              summary="Generate a Google OAuth authorization URL (Step 1)")
 async def create_auth_url(
@@ -78,7 +114,14 @@ async def create_auth_url(
         body.client_id[:8],
         (time.perf_counter() - start) * 1000,
     )
-    return GoogleOAuthAuthUrlResponse(success=True, auth_url=auth_url, state=state)
+    return GoogleOAuthAuthUrlResponse(
+        success=True,
+        auth_url=auth_url,
+        state=state,
+        warning=_refresh_token_warning(
+            access_type=body.access_type, scope=body.scope
+        ),
+    )
 
 
 @router.post("/callback", response_model=GoogleOAuthTokenResponse,

app/models/schemas.py

@@ -915,6 +915,9 @@ class GoogleOAuthAuthUrlResponse(BaseModel):
     success: bool
     auth_url: str
     state: str
+    warning: Optional[str] = Field(
+        None, description="User-facing warning describing refresh-token issuance and validity"
+    )
     error: Optional[str] = None