feat: friendly oauth scope map and sheets spreadsheet delete/list

app/api/v1/google_oauth.py

@@ -17,6 +17,7 @@ from app.models.schemas import (
     GoogleOAuthVerifyResponse,
 )
 from app.services.google_oauth_service import GoogleOAuthError, GoogleOAuthService
+from app.services.google_scope_map import resolve_scope_list
 from app.services.jwt_service import JWTService
 from app.config import get_settings
 
@@ -63,12 +64,20 @@ async def create_auth_url(
     service: GoogleOAuthService = Depends(get_oauth_service),
 ):
     start = time.perf_counter()
+
+    resolved_scopes, scope_errors, dropped_scopes = resolve_scope_list(body.scopes)
+    if scope_errors:
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail="; ".join(scope_errors),
+        )
+
     state = _generate_state()
     auth_url = service.build_auth_url(
         client_id=body.client_id,
         redirect_uri=body.redirect_uri,
         state=state,
-        scope=body.scope,
+        scope=" ".join(resolved_scopes),
         prompt=body.prompt,
         access_type=body.access_type,
         login_hint=body.login_hint,
@@ -83,6 +92,8 @@ async def create_auth_url(
         success=True,
         auth_url=auth_url,
         state=state,
+        resolved_scopes=resolved_scopes,
+        dropped_scopes=dropped_scopes,
     )
 
 

app/api/v1/scopes/__init__.py

@@ -2,11 +2,12 @@ from __future__ import annotations
 
 from fastapi import APIRouter
 
-from . import detail, list, names, set
+from . import detail, list, map, names, set
 
 router = APIRouter(tags=["Google Scopes"])
 _PREFIX = "/google/scopes"
 router.include_router(list.router, prefix=_PREFIX)
 router.include_router(names.router, prefix=_PREFIX)
+router.include_router(map.router, prefix=_PREFIX)
 router.include_router(detail.router, prefix=_PREFIX)
 router.include_router(set.router, prefix=_PREFIX)

app/api/v1/scopes/map.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import time
+from typing import List, Optional
+
+from fastapi import APIRouter, HTTPException, Query
+
+from app.models.schemas import GoogleScopeMapResponse
+from app.services.google_scope_map import CATEGORY_ORDER, SCOPE_MAP
+
+router = APIRouter()
+
+
+@router.get(
+    "/map",
+    response_model=GoogleScopeMapResponse,
+    summary="Friendly Google OAuth scope alias map (grouped by API category)",
+)
+async def get_scope_map(
+    category: Optional[str] = Query(None, description="Return a single category only (e.g. gmail)"),
+    search: Optional[str] = Query(None, description="Free-text search across aliases and scope URIs"),
+) -> GoogleScopeMapResponse:
+    """Return the friendly scope alias -> full URI mapping.
+
+    Clients can read this map to pick short aliases (e.g. ``gmail_full``,
+    ``sheets_readonly``) and then pass them as a list in
+    ``POST /google/oauth/auth-url`` instead of pasting long scope URLs.
+    """
+    started = time.perf_counter()
+
+    def _matches(alias: str, uri: str, needle: Optional[str]) -> bool:
+        if not needle:
+            return True
+        needle_l = needle.lower()
+        return needle_l in alias.lower() or needle_l in uri.lower()
+
+    if category:
+        if category not in SCOPE_MAP:
+            valid = ", ".join(CATEGORY_ORDER)
+            raise HTTPException(
+                status_code=404,
+                detail=f"Unknown category '{category}'. Valid categories: {valid}",
+            )
+        selected: dict = {category: SCOPE_MAP[category]}
+    else:
+        selected = dict(SCOPE_MAP)
+
+    if search:
+        selected = {
+            cat: {
+                alias: uri
+                for alias, uri in entries.items()
+                if _matches(alias, uri, search)
+            }
+            for cat, entries in selected.items()
+            if any(_matches(a, u, search) for a, u in entries.items())
+        }
+
+    total_aliases = sum(len(entries) for entries in selected.values())
+    return GoogleScopeMapResponse(
+        success=True,
+        time_ms=round((time.perf_counter() - started) * 1000, 3),
+        count=total_aliases,
+        categories=list(selected.keys()),
+        map=selected,
+    )

app/api/v1/sheets.py

@@ -162,6 +162,32 @@ async def create_spreadsheet(
     return _ok(start, creds, data)
 
 
+@router.get("/spreadsheets", response_model=SheetsGenericResponse,
+            summary="List all spreadsheets (drive.files.list, filtered to sheets)")
+async def list_spreadsheets(
+    creds: SheetsCredentials = Depends(_credentials),
+    service: SheetsService = Depends(get_sheets_service),
+    page_size: int = 100,
+    page_token: Optional[str] = None,
+    include_trashed: bool = False,
+):
+    start = time.perf_counter()
+    if page_size < 1 or page_size > 1000:
+        raise HTTPException(status_code=400, detail="page_size must be between 1 and 1000.")
+    try:
+        data = await service.list_spreadsheets(
+            creds,
+            page_size=page_size,
+            page_token=page_token,
+            include_trashed=include_trashed,
+        )
+    except SheetsAPIError as exc:
+        raise _http_error(exc) from exc
+    files = (data or {}).get("files", []) or []
+    _logger.info("Sheets listed %d spreadsheets (%.2fms)", len(files), _elapsed_ms(start))
+    return _ok(start, creds, data)
+
+
 @router.get("/spreadsheets/{spreadsheet_id}", response_model=SheetsGenericResponse,
             summary="Get spreadsheet metadata (spreadsheets.get)")
 async def get_spreadsheet(
@@ -185,6 +211,22 @@ async def get_spreadsheet(
     return _ok(start, creds, data)
 
 
+@router.delete("/spreadsheets/{spreadsheet_id}", response_model=SheetsGenericResponse,
+               summary="Delete a spreadsheet (drive.files.delete, pre-validated as a sheet)")
+async def delete_spreadsheet(
+    spreadsheet_id: str,
+    creds: SheetsCredentials = Depends(_credentials),
+    service: SheetsService = Depends(get_sheets_service),
+):
+    start = time.perf_counter()
+    try:
+        data = await service.delete_spreadsheet(creds, spreadsheet_id)
+    except SheetsAPIError as exc:
+        raise _http_error(exc) from exc
+    _logger.info("Sheets spreadsheet %s deleted (%.2fms)", spreadsheet_id, _elapsed_ms(start))
+    return _ok(start, creds, data)
+
+
 @router.get("/spreadsheets/{spreadsheet_id}/sheets/{sheet_id}",
             response_model=SheetsGenericResponse,
             summary="Get a single sheet's metadata (spreadsheets.sheets.get)")

app/config.py

@@ -151,6 +151,11 @@ class Settings(BaseSettings):
     sheets_default_scope: str = "https://www.googleapis.com/auth/spreadsheets"
     sheets_refresh_buffer_seconds: int = 60
 
+    # Google Drive API settings (used to delete spreadsheets — the Sheets API
+    # has no delete method, so removal goes through drive.files.delete).
+    drive_api_base_url: str = "https://www.googleapis.com/drive/v3"
+    drive_default_scope: str = "https://www.googleapis.com/auth/drive.file"
+
     # Media-to-Media conversion settings
     media_output_dir: str = "./data/media-convert"
     media_max_workers: int = 4

app/models/schemas.py

@@ -904,17 +904,47 @@ class GoogleOAuthUserInfo(BaseModel):
 class GoogleOAuthAuthUrlRequest(BaseModel):
     client_id: str = Field(..., min_length=1, max_length=500, description="Google OAuth Client ID")
     redirect_uri: str = Field(..., min_length=1, max_length=1000, description="Registered callback URL")
-    scope: str = Field(default="openid email profile", min_length=1, max_length=2000, description="Space-separated OAuth scopes")
+    scopes: Union[str, List[str]] = Field(
+        default=["openid", "email", "profile"],
+        description=(
+            "OAuth scopes. Accepts a list of friendly aliases (e.g. 'gmail_full') "
+            "and/or full scope URIs, or a single space-separated string for backward "
+            "compatibility. Aliases are resolved via the scope map; unknown names are "
+            "rejected."
+        ),
+    )
     prompt: Optional[str] = Field(None, pattern="^(none|consent|select_account)$", description="Google prompt parameter")
     access_type: Optional[str] = Field(None, pattern="^(online|offline)$", description="Whether to return a refresh token (offline)")
     login_hint: Optional[str] = Field(None, max_length=500, description="Prefilled user email to sign in as")
     include_granted_scopes: bool = Field(default=False, description="Append previously granted scopes")
 
+    @field_validator("scopes")
+    @classmethod
+    def _normalize_scopes(cls, v: Union[str, List[str]]) -> List[str]:
+        if isinstance(v, str):
+            return [s for s in v.split() if s]
+        return [str(s).strip() for s in v]
+
 
 class GoogleOAuthAuthUrlResponse(BaseModel):
     success: bool
     auth_url: str
     state: str
+    resolved_scopes: Optional[List[str]] = Field(
+        None,
+        description=(
+            "The final scope URIs sent to Google after alias resolution, "
+            "de-duplication and normalization (narrower scopes covered by a "
+            "broader one are dropped)."
+        ),
+    )
+    dropped_scopes: Optional[List[str]] = Field(
+        None,
+        description=(
+            "Scope URIs that were requested but omitted from the consent screen "
+            "because a broader scope already grants them."
+        ),
+    )
     error: Optional[str] = None
 
 
@@ -1055,6 +1085,26 @@ class GoogleApiIdsResponse(BaseModel):
     error: Optional[str] = None
 
 
+class GoogleScopeMapEntry(BaseModel):
+    """A single friendly scope alias mapped to its full Google scope URI."""
+
+    alias: str = Field(..., description="Friendly alias the client can request")
+    uri: str = Field(..., description="Full Google OAuth scope URI (or 'openid')")
+    api: Optional[str] = Field(None, description="Human-friendly API/category label")
+    description: Optional[str] = Field(None, description="What the scope allows")
+
+
+class GoogleScopeMapResponse(BaseModel):
+    """The full friendly-alias to scope-URI mapping, grouped by category."""
+
+    success: bool
+    time_ms: float
+    count: int = 0
+    categories: List[str] = Field(default_factory=list, description="Ordered category keys")
+    map: Dict[str, Dict[str, str]] = Field(default_factory=dict, description="Category -> {alias: scope URI}")
+    error: Optional[str] = None
+
+
 class GoogleSetScopesRequest(BaseModel):
     """Set the current scopes for one or more Google integrations."""
 
@@ -2021,16 +2071,19 @@ class GmailRefreshResponse(BaseModel):
 class SheetsScope(Enum):
     """All Sheets-specific OAuth scopes (developers.google.com/sheets/api/auth).
 
-    Drive scopes are intentionally excluded here — they belong to the separate
-    Google Drive API integration.
+    Includes the Drive scopes required to delete a spreadsheet — the Sheets API
+    has no ``spreadsheets.delete`` method, so removal goes through the Drive
+    API (``drive.files.delete``) which needs ``drive.file`` or ``drive``.
     """
 
     READONLY = "https://www.googleapis.com/auth/spreadsheets.readonly"
     SPREADSHEETS = "https://www.googleapis.com/auth/spreadsheets"
+    DRIVE_FILE = "https://www.googleapis.com/auth/drive.file"
+    DRIVE = "https://www.googleapis.com/auth/drive"
 
     @property
     def permission_level(self) -> str:
-        return "sensitive"
+        return "restricted" if self in (SheetsScope.DRIVE_FILE, SheetsScope.DRIVE) else "sensitive"
 
 
 class SheetsCreateSpreadsheetRequest(BaseModel):

app/services/google_scope_map.py

@@ -0,0 +1,532 @@
+from __future__ import annotations
+
+from typing import Dict, List, Optional, Tuple
+
+# Friendly Google OAuth scope map.
+#
+# ``SCOPE_MAP`` groups every Google OAuth scope under a human-friendly category
+# and gives each scope a short alias. Clients can request scopes by alias in
+# POST /google/oauth/auth-url instead of pasting long scope URIs, e.g.
+# ``["openid", "email", "gmail_full"]``.
+#
+# Generic full scope URIs are also accepted verbatim (the map is a convenience,
+# not a restriction). Validation only rejects empty/unknown scope names.
+
+SCOPE_MAP: Dict[str, Dict[str, str]] = {
+    "authentication": {
+        "openid": "openid",
+        "email": "https://www.googleapis.com/auth/userinfo.email",
+        "profile": "https://www.googleapis.com/auth/userinfo.profile",
+        "userinfo_email": "https://www.googleapis.com/auth/userinfo.email",
+        "userinfo_profile": "https://www.googleapis.com/auth/userinfo.profile",
+    },
+    "gmail": {
+        "gmail_full": "https://www.googleapis.com/auth/gmail.modify",
+        "gmail_readonly": "https://www.googleapis.com/auth/gmail.readonly",
+        "gmail_send": "https://www.googleapis.com/auth/gmail.send",
+        "gmail_compose": "https://www.googleapis.com/auth/gmail.compose",
+        "gmail_metadata": "https://www.googleapis.com/auth/gmail.metadata",
+        "gmail_insert": "https://www.googleapis.com/auth/gmail.insert",
+        "gmail_labels": "https://www.googleapis.com/auth/gmail.labels",
+        "gmail_settings_basic": "https://www.googleapis.com/auth/gmail.settings.basic",
+        "gmail_settings_sharing": "https://www.googleapis.com/auth/gmail.settings.sharing",
+        "gmail_permanent_delete": "https://mail.google.com/",
+        "gmail_addons_current_action_compose": "https://www.googleapis.com/auth/gmail.addons.current.action.compose",
+        "gmail_addons_current_message_action": "https://www.googleapis.com/auth/gmail.addons.current.message.action",
+        "gmail_addons_current_message_metadata": "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
+        "gmail_addons_current_message_readonly": "https://www.googleapis.com/auth/gmail.addons.current.message.readonly",
+    },
+    "google_sheets": {
+        "sheets_readwrite": "https://www.googleapis.com/auth/spreadsheets",
+        "sheets_readonly": "https://www.googleapis.com/auth/spreadsheets.readonly",
+        "sheets_drive_file": "https://www.googleapis.com/auth/drive.file",
+        "sheets_drive_readonly": "https://www.googleapis.com/auth/drive.readonly",
+        "sheets_drive_full": "https://www.googleapis.com/auth/drive",
+    },
+    "google_drive": {
+        "drive_file": "https://www.googleapis.com/auth/drive.file",
+        "drive_metadata_readonly": "https://www.googleapis.com/auth/drive.metadata.readonly",
+        "drive_readonly": "https://www.googleapis.com/auth/drive.readonly",
+        "drive_full": "https://www.googleapis.com/auth/drive",
+        "drive_metadata": "https://www.googleapis.com/auth/drive.metadata",
+        "drive_appdata": "https://www.googleapis.com/auth/drive.appdata",
+        "drive_apps_readonly": "https://www.googleapis.com/auth/drive.apps.readonly",
+        "drive_scripts": "https://www.googleapis.com/auth/drive.scripts",
+        "drive_install": "https://www.googleapis.com/auth/drive.install",
+        "drive_activity": "https://www.googleapis.com/auth/drive.activity",
+        "drive_activity_readonly": "https://www.googleapis.com/auth/drive.activity.readonly",
+        "drive_photos_readonly": "https://www.googleapis.com/auth/drive.photos.readonly",
+        "drive_meet_readonly": "https://www.googleapis.com/auth/drive.meet.readonly",
+    },
+    "google_docs": {
+        "docs_readwrite": "https://www.googleapis.com/auth/documents",
+        "docs_readonly": "https://www.googleapis.com/auth/documents.readonly",
+        "docs_drive_file": "https://www.googleapis.com/auth/drive.file",
+        "docs_drive_readonly": "https://www.googleapis.com/auth/drive.readonly",
+        "docs_drive_full": "https://www.googleapis.com/auth/drive",
+    },
+    "google_slides": {
+        "slides_readwrite": "https://www.googleapis.com/auth/presentations",
+        "slides_readonly": "https://www.googleapis.com/auth/presentations.readonly",
+        "slides_drive_file": "https://www.googleapis.com/auth/drive.file",
+        "slides_drive_readonly": "https://www.googleapis.com/auth/drive.readonly",
+        "slides_drive_full": "https://www.googleapis.com/auth/drive",
+    },
+    "google_calendar": {
+        "calendar_full": "https://www.googleapis.com/auth/calendar",
+        "calendar_readonly": "https://www.googleapis.com/auth/calendar.readonly",
+        "calendar_events": "https://www.googleapis.com/auth/calendar.events",
+        "calendar_events_readonly": "https://www.googleapis.com/auth/calendar.events.readonly",
+        "calendar_events_owned": "https://www.googleapis.com/auth/calendar.events.owned",
+        "calendar_events_owned_readonly": "https://www.googleapis.com/auth/calendar.events.owned.readonly",
+        "calendar_events_public_readonly": "https://www.googleapis.com/auth/calendar.events.public.readonly",
+        "calendar_events_freebusy": "https://www.googleapis.com/auth/calendar.events.freebusy",
+        "calendar_freebusy": "https://www.googleapis.com/auth/calendar.freebusy",
+        "calendar_settings_readonly": "https://www.googleapis.com/auth/calendar.settings.readonly",
+        "calendar_calendarlist": "https://www.googleapis.com/auth/calendar.calendarlist",
+        "calendar_calendarlist_readonly": "https://www.googleapis.com/auth/calendar.calendarlist.readonly",
+        "calendar_calendars": "https://www.googleapis.com/auth/calendar.calendars",
+        "calendar_calendars_readonly": "https://www.googleapis.com/auth/calendar.calendars.readonly",
+        "calendar_acls": "https://www.googleapis.com/auth/calendar.acls",
+        "calendar_acls_readonly": "https://www.googleapis.com/auth/calendar.acls.readonly",
+        "calendar_app_created": "https://www.googleapis.com/auth/calendar.app.created",
+        "calendar_addons_execute": "https://www.googleapis.com/auth/calendar.addons.execute",
+        "calendar_addons_current_event_read": "https://www.googleapis.com/auth/calendar.addons.current.event.read",
+        "calendar_addons_current_event_write": "https://www.googleapis.com/auth/calendar.addons.current.event.write",
+    },
+    "google_contacts": {
+        "contacts_full": "https://www.googleapis.com/auth/contacts",
+        "contacts_readonly": "https://www.googleapis.com/auth/contacts.readonly",
+        "contacts_other_readonly": "https://www.googleapis.com/auth/contacts.other.readonly",
+        "contacts_directory_readonly": "https://www.googleapis.com/auth/directory.readonly",
+    },
+    "google_tasks": {
+        "tasks_readwrite": "https://www.googleapis.com/auth/tasks",
+        "tasks_readonly": "https://www.googleapis.com/auth/tasks.readonly",
+    },
+    "google_photos": {
+        "photos_library_full": "https://www.googleapis.com/auth/photoslibrary",
+        "photos_library_readonly": "https://www.googleapis.com/auth/photoslibrary.readonly",
+        "photos_library_appendonly": "https://www.googleapis.com/auth/photoslibrary.appendonly",
+        "photos_library_edit_appcreated": "https://www.googleapis.com/auth/photoslibrary.edit.appcreateddata",
+        "photos_library_readonly_appcreated": "https://www.googleapis.com/auth/photoslibrary.readonly.appcreateddata",
+        "photos_library_sharing": "https://www.googleapis.com/auth/photoslibrary.sharing",
+    },
+    "google_chat": {
+        "chat_messages": "https://www.googleapis.com/auth/chat.messages",
+        "chat_messages_readonly": "https://www.googleapis.com/auth/chat.messages.readonly",
+        "chat_spaces": "https://www.googleapis.com/auth/chat.spaces",
+        "chat_spaces_readonly": "https://www.googleapis.com/auth/chat.spaces.readonly",
+        "chat_import": "https://www.googleapis.com/auth/chat.import",
+        "chat_apps_configuration": "https://www.googleapis.com/auth/chat.apps.configuration",
+        "chat_apps_configuration_readonly": "https://www.googleapis.com/auth/chat.apps.configuration.readonly",
+        "chat_apps_readonly": "https://www.googleapis.com/auth/chat.apps.readonly",
+        "chat_pushes": "https://www.googleapis.com/auth/chat.pushes",
+        "chat_meetings": "https://www.googleapis.com/auth/chat.meetings",
+        "chat_meetings_readonly": "https://www.googleapis.com/auth/chat.meetings.readonly",
+    },
+    "google_meet": {
+        "meet_recordings_readonly": "https://www.googleapis.com/auth/drive.meet.readonly",
+    },
+    "google_forms": {
+        "forms_full": "https://www.googleapis.com/auth/forms",
+        "forms_responses_readonly": "https://www.googleapis.com/auth/forms.responses.readonly",
+    },
+    "google_classroom": {
+        "classroom_courses": "https://www.googleapis.com/auth/classroom.courses",
+        "classroom_courses_readonly": "https://www.googleapis.com/auth/classroom.courses.readonly",
+        "classroom_rosters": "https://www.googleapis.com/auth/classroom.rosters",
+        "classroom_rosters_readonly": "https://www.googleapis.com/auth/classroom.rosters.readonly",
+        "classroom_profile_emails": "https://www.googleapis.com/auth/classroom.profile.emails",
+        "classroom_profile_photos": "https://www.googleapis.com/auth/classroom.profile.photos",
+        "classroom_announcements": "https://www.googleapis.com/auth/classroom.announcements",
+        "classroom_announcements_readonly": "https://www.googleapis.com/auth/classroom.announcements.readonly",
+        "classroom_topics": "https://www.googleapis.com/auth/classroom.topics",
+        "classroom_topics_readonly": "https://www.googleapis.com/auth/classroom.topics.readonly",
+        "classroom_coursework_students": "https://www.googleapis.com/auth/classroom.coursework.students",
+        "classroom_coursework_students_readonly": "https://www.googleapis.com/auth/classroom.coursework.students.readonly",
+        "classroom_coursework_me": "https://www.googleapis.com/auth/classroom.coursework.me",
+        "classroom_coursework_me_readonly": "https://www.googleapis.com/auth/classroom.coursework.me.readonly",
+        "classroom_courseworkmaterials": "https://www.googleapis.com/auth/classroom.courseworkmaterials",
+        "classroom_courseworkmaterials_readonly": "https://www.googleapis.com/auth/classroom.courseworkmaterials.readonly",
+        "classroom_guardianlinks_students": "https://www.googleapis.com/auth/classroom.guardianlinks.students",
+        "classroom_guardianlinks_students_readonly": "https://www.googleapis.com/auth/classroom.guardianlinks.students.readonly",
+        "classroom_student_submissions_me_readonly": "https://www.googleapis.com/auth/classroom.student-submissions.me.readonly",
+        "classroom_student_submissions_students_readonly": "https://www.googleapis.com/auth/classroom.student-submissions.students.readonly",
+    },
+    "google_analytics": {
+        "analytics_full": "https://www.googleapis.com/auth/analytics",
+        "analytics_readonly": "https://www.googleapis.com/auth/analytics.readonly",
+        "analytics_edit": "https://www.googleapis.com/auth/analytics.edit",
+        "analytics_manage_users": "https://www.googleapis.com/auth/analytics.manage.users",
+        "analytics_manage_users_readonly": "https://www.googleapis.com/auth/analytics.manage.users.readonly",
+        "analytics_manage_edit": "https://www.googleapis.com/auth/analytics.manage.edit",
+        "analytics_manage_partners": "https://www.googleapis.com/auth/analytics.manage.partners",
+        "analytics_provision": "https://www.googleapis.com/auth/analytics.provision",
+    },
+    "google_ads": {
+        "google_ads_full": "https://www.googleapis.com/auth/adwords",
+        "admanager_readonly": "https://www.googleapis.com/auth/admanager.readonly",
+    },
+    "google_cloud": {
+        "bigquery_readonly": "https://www.googleapis.com/auth/bigquery.readonly",
+        "bigquery_full": "https://www.googleapis.com/auth/bigquery",
+        "bigquery_insertdata": "https://www.googleapis.com/auth/bigquery.insertdata",
+        "cloud_platform": "https://www.googleapis.com/auth/cloud-platform",
+        "cloud_platform_readonly": "https://www.googleapis.com/auth/cloud-platform.read-only",
+        "devstorage_read_only": "https://www.googleapis.com/auth/devstorage.read_only",
+        "devstorage_read_write": "https://www.googleapis.com/auth/devstorage.read_write",
+        "devstorage_full_control": "https://www.googleapis.com/auth/devstorage.full_control",
+        "compute_readonly": "https://www.googleapis.com/auth/compute.readonly",
+        "compute_full": "https://www.googleapis.com/auth/compute",
+        "datastore": "https://www.googleapis.com/auth/datastore",
+        "sqlservice_admin": "https://www.googleapis.com/auth/sqlservice.admin",
+        "vision": "https://www.googleapis.com/auth/cloud-vision",
+        "translate": "https://www.googleapis.com/auth/cloud-translation",
+        "language": "https://www.googleapis.com/auth/cloud-language",
+        "genai": "https://www.googleapis.com/auth/genai",
+    },
+    "google_maps": {},
+    "youtube": {
+        "youtube_readonly": "https://www.googleapis.com/auth/youtube.readonly",
+        "youtube_full": "https://www.googleapis.com/auth/youtube",
+        "youtube_upload": "https://www.googleapis.com/auth/youtube.upload",
+        "youtube_force_ssl": "https://www.googleapis.com/auth/youtube.force-ssl",
+        "youtube_channel_memberships_creator": "https://www.googleapis.com/auth/youtube.channel-memberships.creator",
+        "youtube_partner": "https://www.googleapis.com/auth/youtubepartner",
+        "youtube_partner_channel_audit": "https://www.googleapis.com/auth/youtubepartner-channel-audit",
+    },
+    "google_play": {
+        "play_androidpublisher": "https://www.googleapis.com/auth/androidpublisher",
+        "play_games": "https://www.googleapis.com/auth/playgames",
+        "play_games_readonly": "https://www.googleapis.com/auth/playgames.readonly",
+    },
+    "firebase": {
+        "firebase_full": "https://www.googleapis.com/auth/firebase",
+        "firebase_readonly": "https://www.googleapis.com/auth/firebase.readonly",
+        "firebase_database": "https://www.googleapis.com/auth/firebase.database",
+        "firebase_database_readonly": "https://www.googleapis.com/auth/firebase.database.readonly",
+        "firebase_messaging": "https://www.googleapis.com/auth/firebase.messaging",
+        "firebase_rules": "https://www.googleapis.com/auth/firebase.rules",
+        "firebase_rules_readonly": "https://www.googleapis.com/auth/firebase.rules.readonly",
+        "firebase_analytics": "https://www.googleapis.com/auth/firebase.analytics",
+    },
+    "admin_sdk": {
+        "admin_directory_user_readonly": "https://www.googleapis.com/auth/admin.directory.user.readonly",
+        "admin_directory_user": "https://www.googleapis.com/auth/admin.directory.user",
+        "admin_directory_group_readonly": "https://www.googleapis.com/auth/admin.directory.group.readonly",
+        "admin_directory_group": "https://www.googleapis.com/auth/admin.directory.group",
+        "admin_directory_group_member_readonly": "https://www.googleapis.com/auth/admin.directory.group.member.readonly",
+        "admin_directory_group_member": "https://www.googleapis.com/auth/admin.directory.group.member",
+        "admin_directory_device_chromeos_readonly": "https://www.googleapis.com/auth/admin.directory.device.chromeos.readonly",
+        "admin_directory_device_chromeos": "https://www.googleapis.com/auth/admin.directory.device.chromeos",
+        "admin_directory_orgunit_readonly": "https://www.googleapis.com/auth/admin.directory.orgunit.readonly",
+        "admin_directory_orgunit": "https://www.googleapis.com/auth/admin.directory.orgunit",
+        "admin_directory_rolemanagement_readonly": "https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly",
+        "admin_directory_rolemanagement": "https://www.googleapis.com/auth/admin.directory.rolemanagement",
+        "admin_directory_domain_readonly": "https://www.googleapis.com/auth/admin.directory.domain.readonly",
+        "admin_directory_customer_readonly": "https://www.googleapis.com/auth/admin.directory.customer.readonly",
+        "admin_directory_userschema_readonly": "https://www.googleapis.com/auth/admin.directory.userschema.readonly",
+        "admin_reports_audit_readonly": "https://www.googleapis.com/auth/admin.reports.audit.readonly",
+        "admin_reports_usage_readonly": "https://www.googleapis.com/auth/admin.reports.usage.readonly",
+        "admin_datatransfer": "https://www.googleapis.com/auth/admin.datatransfer",
+    },
+    "people_api": {
+        "people_contacts_full": "https://www.googleapis.com/auth/contacts",
+        "people_contacts_readonly": "https://www.googleapis.com/auth/contacts.readonly",
+        "people_othercontacts": "https://www.googleapis.com/auth/people.otherContacts",
+        "people_othercontacts_readonly": "https://www.googleapis.com/auth/people.otherContacts.readonly",
+        "people_email_readonly": "https://www.googleapis.com/auth/people.emailAddresses.readonly",
+        "people_phone_readonly": "https://www.googleapis.com/auth/people.phoneNumbers.readonly",
+        "people_contactinfo": "https://www.googleapis.com/auth/people.contactInfo",
+        "people_contactinfo_readonly": "https://www.googleapis.com/auth/people.contactInfo.readonly",
+        "people_directory_readonly": "https://www.googleapis.com/auth/people.directory.readonly",
+        "user_emails_readonly": "https://www.googleapis.com/auth/user.emails.readonly",
+        "user_phonenumbers_readonly": "https://www.googleapis.com/auth/user.phonenumbers.readonly",
+    },
+    "business_profile": {
+        "business_manage": "https://www.googleapis.com/auth/business.manage",
+    },
+    "other": {
+        "openid": "openid",
+        "email": "https://www.googleapis.com/auth/userinfo.email",
+        "profile": "https://www.googleapis.com/auth/userinfo.profile",
+    },
+}
+
+CATEGORY_ORDER: List[str] = list(SCOPE_MAP.keys())
+
+ALIAS_TO_URI: Dict[str, str] = {
+    alias: uri
+    for category in SCOPE_MAP.values()
+    for alias, uri in category.items()
+}
+
+ALL_ALIASES: List[str] = sorted(ALIAS_TO_URI)
+
+# Scope containment for UX normalization. When a broader scope is already in
+# the request, narrower scopes of the same family are redundant and are dropped
+# so the Google consent screen stays minimal. Only documented supersets are
+# listed; generic/unknown scopes are never touched.
+_SCOPE_INCLUDED_BY: Dict[str, Tuple[str, ...]] = {
+    # --- Gmail family ---
+    "https://www.googleapis.com/auth/gmail.metadata": (
+        "https://www.googleapis.com/auth/gmail.readonly",
+        "https://www.googleapis.com/auth/gmail.modify",
+        "https://mail.google.com/",
+    ),
+    "https://www.googleapis.com/auth/gmail.readonly": (
+        "https://www.googleapis.com/auth/gmail.modify",
+        "https://mail.google.com/",
+    ),
+    "https://www.googleapis.com/auth/gmail.labels": (
+        "https://www.googleapis.com/auth/gmail.modify",
+        "https://mail.google.com/",
+    ),
+    "https://www.googleapis.com/auth/gmail.send": (
+        "https://www.googleapis.com/auth/gmail.compose",
+        "https://www.googleapis.com/auth/gmail.modify",
+        "https://mail.google.com/",
+    ),
+    "https://www.googleapis.com/auth/gmail.compose": (
+        "https://www.googleapis.com/auth/gmail.modify",
+        "https://mail.google.com/",
+    ),
+    "https://www.googleapis.com/auth/gmail.modify": (
+        "https://mail.google.com/",
+    ),
+    # --- Sheets / Drive family ---
+    "https://www.googleapis.com/auth/spreadsheets.readonly": (
+        "https://www.googleapis.com/auth/spreadsheets",
+    ),
+    "https://www.googleapis.com/auth/drive.metadata.readonly": (
+        "https://www.googleapis.com/auth/drive.readonly",
+        "https://www.googleapis.com/auth/drive.metadata",
+        "https://www.googleapis.com/auth/drive",
+    ),
+    "https://www.googleapis.com/auth/drive.metadata": (
+        "https://www.googleapis.com/auth/drive",
+    ),
+    "https://www.googleapis.com/auth/drive.readonly": (
+        "https://www.googleapis.com/auth/drive",
+    ),
+    "https://www.googleapis.com/auth/drive.file": (
+        "https://www.googleapis.com/auth/drive",
+    ),
+    "https://www.googleapis.com/auth/drive.appdata": (
+        "https://www.googleapis.com/auth/drive",
+    ),
+    "https://www.googleapis.com/auth/drive.scripts": (
+        "https://www.googleapis.com/auth/drive",
+    ),
+    "https://www.googleapis.com/auth/drive.activity.readonly": (
+        "https://www.googleapis.com/auth/drive.activity",
+        "https://www.googleapis.com/auth/drive",
+    ),
+    "https://www.googleapis.com/auth/drive.activity": (
+        "https://www.googleapis.com/auth/drive",
+    ),
+    "https://www.googleapis.com/auth/drive.photos.readonly": (
+        "https://www.googleapis.com/auth/drive",
+    ),
+    "https://www.googleapis.com/auth/drive.meet.readonly": (
+        "https://www.googleapis.com/auth/drive",
+    ),
+    # --- Calendar family ---
+    "https://www.googleapis.com/auth/calendar.events.readonly": (
+        "https://www.googleapis.com/auth/calendar.events",
+        "https://www.googleapis.com/auth/calendar.readonly",
+        "https://www.googleapis.com/auth/calendar",
+    ),
+    "https://www.googleapis.com/auth/calendar.events": (
+        "https://www.googleapis.com/auth/calendar",
+    ),
+    "https://www.googleapis.com/auth/calendar.events.owned.readonly": (
+        "https://www.googleapis.com/auth/calendar.events.owned",
+        "https://www.googleapis.com/auth/calendar.events.readonly",
+        "https://www.googleapis.com/auth/calendar.readonly",
+        "https://www.googleapis.com/auth/calendar",
+    ),
+    "https://www.googleapis.com/auth/calendar.events.owned": (
+        "https://www.googleapis.com/auth/calendar.events",
+        "https://www.googleapis.com/auth/calendar",
+    ),
+    "https://www.googleapis.com/auth/calendar.events.public.readonly": (
+        "https://www.googleapis.com/auth/calendar.readonly",
+        "https://www.googleapis.com/auth/calendar",
+    ),
+    "https://www.googleapis.com/auth/calendar.events.freebusy": (
+        "https://www.googleapis.com/auth/calendar.freebusy",
+        "https://www.googleapis.com/auth/calendar",
+    ),
+    "https://www.googleapis.com/auth/calendar.readonly": (
+        "https://www.googleapis.com/auth/calendar",
+    ),
+    "https://www.googleapis.com/auth/calendar.freebusy": (
+        "https://www.googleapis.com/auth/calendar",
+    ),
+    "https://www.googleapis.com/auth/calendar.settings.readonly": (
+        "https://www.googleapis.com/auth/calendar",
+    ),
+    "https://www.googleapis.com/auth/calendar.calendarlist.readonly": (
+        "https://www.googleapis.com/auth/calendar.calendarlist",
+        "https://www.googleapis.com/auth/calendar",
+    ),
+    "https://www.googleapis.com/auth/calendar.calendarlist": (
+        "https://www.googleapis.com/auth/calendar",
+    ),
+    "https://www.googleapis.com/auth/calendar.calendars.readonly": (
+        "https://www.googleapis.com/auth/calendar.calendars",
+        "https://www.googleapis.com/auth/calendar",
+    ),
+    "https://www.googleapis.com/auth/calendar.calendars": (
+        "https://www.googleapis.com/auth/calendar",
+    ),
+    "https://www.googleapis.com/auth/calendar.acls.readonly": (
+        "https://www.googleapis.com/auth/calendar.acls",
+        "https://www.googleapis.com/auth/calendar",
+    ),
+    "https://www.googleapis.com/auth/calendar.acls": (
+        "https://www.googleapis.com/auth/calendar",
+    ),
+    # --- Contacts / People family ---
+    "https://www.googleapis.com/auth/contacts.readonly": (
+        "https://www.googleapis.com/auth/contacts",
+    ),
+    "https://www.googleapis.com/auth/contacts.other.readonly": (
+        "https://www.googleapis.com/auth/contacts",
+    ),
+    # --- Tasks family ---
+    "https://www.googleapis.com/auth/tasks.readonly": (
+        "https://www.googleapis.com/auth/tasks",
+    ),
+    # --- YouTube family ---
+    "https://www.googleapis.com/auth/youtube.readonly": (
+        "https://www.googleapis.com/auth/youtube.force-ssl",
+        "https://www.googleapis.com/auth/youtube",
+    ),
+    "https://www.googleapis.com/auth/youtube.upload": (
+        "https://www.googleapis.com/auth/youtube",
+    ),
+    "https://www.googleapis.com/auth/youtube.force-ssl": (
+        "https://www.googleapis.com/auth/youtube",
+    ),
+    "https://www.googleapis.com/auth/youtube.channel-memberships.creator": (
+        "https://www.googleapis.com/auth/youtube",
+    ),
+    "https://www.googleapis.com/auth/youtubepartner-channel-audit": (
+        "https://www.googleapis.com/auth/youtubepartner",
+    ),
+    # --- Forms family ---
+    "https://www.googleapis.com/auth/forms.responses.readonly": (
+        "https://www.googleapis.com/auth/forms",
+    ),
+    # --- Analytics family ---
+    "https://www.googleapis.com/auth/analytics.readonly": (
+        "https://www.googleapis.com/auth/analytics.edit",
+        "https://www.googleapis.com/auth/analytics",
+    ),
+    "https://www.googleapis.com/auth/analytics.edit": (
+        "https://www.googleapis.com/auth/analytics",
+    ),
+    "https://www.googleapis.com/auth/analytics.manage.users.readonly": (
+        "https://www.googleapis.com/auth/analytics.manage.users",
+    ),
+    # --- BigQuery / Cloud family ---
+    "https://www.googleapis.com/auth/bigquery.readonly": (
+        "https://www.googleapis.com/auth/bigquery",
+    ),
+    "https://www.googleapis.com/auth/bigquery.insertdata": (
+        "https://www.googleapis.com/auth/bigquery",
+    ),
+    "https://www.googleapis.com/auth/cloud-platform.read-only": (
+        "https://www.googleapis.com/auth/cloud-platform",
+    ),
+    "https://www.googleapis.com/auth/devstorage.read_only": (
+        "https://www.googleapis.com/auth/devstorage.read_write",
+        "https://www.googleapis.com/auth/devstorage.full_control",
+    ),
+    "https://www.googleapis.com/auth/devstorage.read_write": (
+        "https://www.googleapis.com/auth/devstorage.full_control",
+    ),
+    # --- Admin SDK family ---
+    "https://www.googleapis.com/auth/admin.directory.user.readonly": (
+        "https://www.googleapis.com/auth/admin.directory.user",
+    ),
+    "https://www.googleapis.com/auth/admin.directory.group.readonly": (
+        "https://www.googleapis.com/auth/admin.directory.group",
+    ),
+    "https://www.googleapis.com/auth/admin.directory.group.member.readonly": (
+        "https://www.googleapis.com/auth/admin.directory.group.member",
+    ),
+    "https://www.googleapis.com/auth/admin.directory.device.chromeos.readonly": (
+        "https://www.googleapis.com/auth/admin.directory.device.chromeos",
+    ),
+    "https://www.googleapis.com/auth/admin.directory.orgunit.readonly": (
+        "https://www.googleapis.com/auth/admin.directory.orgunit",
+    ),
+    "https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly": (
+        "https://www.googleapis.com/auth/admin.directory.rolemanagement",
+    ),
+}
+
+
+def is_generic_scope(value: str) -> bool:
+    """True when the value is a full scope URI the client typed directly."""
+    return value.startswith(("http://", "https://", "mail.google.com/")) or value == "openid"
+
+
+def _normalize_scopes(resolved: List[str]) -> Tuple[List[str], List[str]]:
+    """Drop scopes already covered by a broader scope in the same request.
+
+    Returns ``(kept_scopes, dropped_scopes)``. Order of the remaining scopes is
+    preserved. Unknown/generic scopes (not in the containment table) are never
+    dropped.
+    """
+    present = set(resolved)
+    kept: List[str] = []
+    dropped: List[str] = []
+    for uri in resolved:
+        supersets = _SCOPE_INCLUDED_BY.get(uri, ())
+        if any(superset in present for superset in supersets):
+            dropped.append(uri)
+            continue
+        kept.append(uri)
+    return kept, dropped
+
+
+def resolve_scope_list(
+    scopes: Optional[List[str]], *, normalize: bool = True
+) -> Tuple[List[str], List[str], List[str]]:
+    """Resolve a list of scope aliases / URIs into a de-duplicated list of URIs.
+
+    Returns ``(resolved_uris, errors, dropped_scopes)``. Generic full scope URIs
+    are accepted verbatim; only empty or unknown scope names produce errors.
+    When ``normalize`` is true, narrower scopes that are fully covered by a
+    broader scope already present are dropped (best UX: minimal consent screen).
+    """
+    resolved: List[str] = []
+    errors: List[str] = []
+    dropped: List[str] = []
+    seen = set()
+    for raw in scopes or []:
+        value = str(raw or "").strip()
+        if not value:
+            errors.append("Scope name is missing (empty entry).")
+            continue
+        if value in ALIAS_TO_URI:
+            uri = ALIAS_TO_URI[value]
+        elif is_generic_scope(value):
+            uri = value
+        else:
+            errors.append(
+                f"Unknown scope '{value}'. It is not a known alias and not a full scope URI. "
+                f"Valid aliases: {', '.join(ALL_ALIASES)}"
+            )
+            continue
+        if uri not in seen:
+            seen.add(uri)
+            resolved.append(uri)
+    if normalize:
+        resolved, dropped = _normalize_scopes(resolved)
+    return resolved, errors, dropped

app/services/sheets_service.py

@@ -91,8 +91,9 @@ class SheetsService:
         *,
         params: Optional[Dict[str, Any]] = None,
         json_body: Optional[Any] = None,
+        base_url: Optional[str] = None,
     ) -> Any:
-        """Send a Sheets API request with proactive + on-401 refresh and retries."""
+        """Send a Sheets/Drive API request with proactive + on-401 refresh and retries."""
         if creds.needs_proactive_refresh:
             await self._refresh(creds, context=f"{method} {path}")
 
@@ -100,7 +101,7 @@ class SheetsService:
         attempt = 0
         while True:
             response = await self._send(
-                creds, method, path, params=params, json_body=json_body
+                creds, method, path, params=params, json_body=json_body, base_url=base_url
             )
             if 200 <= response.status_code < 300:
                 return self._decode(response)
@@ -130,9 +131,10 @@ class SheetsService:
         *,
         params: Optional[Dict[str, Any]] = None,
         json_body: Optional[Any] = None,
+        base_url: Optional[str] = None,
     ) -> httpx.Response:
         client = await self._get_client()
-        url = f"{_settings.sheets_api_base_url}{path}"
+        url = f"{base_url or _settings.sheets_api_base_url}{path}"
         headers = {
             "Authorization": f"Bearer {creds.access_token}",
             "Accept": "application/json",
@@ -388,6 +390,96 @@ class SheetsService:
             body["sheets"] = sheets
         return await self._request(creds, "POST", "/spreadsheets", json_body=body)
 
+    _SPREADSHEET_MIME_TYPE = "application/vnd.google-apps.spreadsheet"
+
+    async def get_drive_file(
+        self,
+        creds: SheetsCredentials,
+        file_id: str,
+    ) -> Dict[str, Any]:
+        """Read a Drive file's metadata (drive.files.get) — used to validate the
+        target before deletion so arbitrary non-sheet files cannot be removed."""
+        return await self._request(
+            creds,
+            "GET",
+            f"/files/{file_id}",
+            params={"fields": "id,name,mimeType,trashed"},
+            base_url=_settings.drive_api_base_url,
+        )
+
+    async def list_spreadsheets(
+        self,
+        creds: SheetsCredentials,
+        *,
+        page_size: int = 100,
+        page_token: Optional[str] = None,
+        include_trashed: bool = False,
+    ) -> Dict[str, Any]:
+        """List the user's Google Sheets via drive.files.list.
+
+        Filters to ``application/vnd.google-apps.spreadsheet`` so only
+        spreadsheets are returned (no arbitrary Drive files). The Sheets API has
+        no list endpoint; Drive's ``files.list`` with a ``q`` filter is the
+        documented way to enumerate spreadsheets.
+        """
+        query = f"mimeType='{self._SPREADSHEET_MIME_TYPE}'"
+        if not include_trashed:
+            query += " and trashed=false"
+
+        params: Dict[str, Any] = {
+            "q": query,
+            "pageSize": page_size,
+            "fields": "nextPageToken,files(id,name,mimeType,trashed,modifiedTime)",
+        }
+        if page_token:
+            params["pageToken"] = page_token
+        return await self._request(
+            creds,
+            "GET",
+            "/files",
+            params=params,
+            base_url=_settings.drive_api_base_url,
+        )
+
+
+    async def delete_spreadsheet(
+        self,
+        creds: SheetsCredentials,
+        spreadsheet_id: str,
+    ) -> Dict[str, Any]:
+        """Delete a spreadsheet via drive.files.delete.
+
+        Pre-validates with drive.files.get that the target file is a Google
+        Sheet (``mimeType == application/vnd.google-apps.spreadsheet``) so this
+        endpoint can never remove an arbitrary Drive file. Requires the
+        ``drive.file`` (or broader ``drive``) OAuth scope — the Sheets API has no
+        delete method.
+        """
+        file_meta = await self.get_drive_file(creds, spreadsheet_id)
+        mime = (file_meta or {}).get("mimeType")
+        if mime != self._SPREADSHEET_MIME_TYPE:
+            raise SheetsAPIError(
+                f"Refusing to delete '{spreadsheet_id}': it is not a Google Sheet "
+                f"(mimeType={mime or 'unknown'}). Only spreadsheets can be removed "
+                "through the spreadsheet delete API.",
+                status_code=400,
+                reason="INVALID_MIME_TYPE",
+            )
+
+        await self._request(
+            creds,
+            "DELETE",
+            f"/files/{spreadsheet_id}",
+            base_url=_settings.drive_api_base_url,
+        )
+        return {
+            "spreadsheetId": spreadsheet_id,
+            "mimeType": mime,
+            "name": file_meta.get("name"),
+            "deleted": True,
+        }
+
+
     async def get_spreadsheet(
         self,
         creds: SheetsCredentials,