gmail-agent 0.3.0__py3-none-any.whl

gmail_agent/__init__.py

@@ -0,0 +1,8 @@
+"""Gmail for AI agents: a CLI and an MCP server."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("gmail-agent")  # pyproject.toml is the one place the version lives
+except PackageNotFoundError:  # a source tree that was never installed
+    __version__ = "0+unknown"

gmail_agent/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

gmail_agent/auth.py

@@ -0,0 +1,231 @@
+"""OAuth: the one-time browser login, and loading/refreshing the saved token."""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import sys
+import tempfile
+import threading
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from google.auth.exceptions import RefreshError, TransportError
+from google.auth.transport.requests import Request
+from google.oauth2.credentials import Credentials
+
+from . import config
+from .errors import GmailAgentError, SetupError
+
+SETUP_HINT = "See https://github.com/dremok/gmail-agent#google-cloud-setup"
+CONSOLE = "https://console.cloud.google.com"
+LOGIN_TIMEOUT = 300  # seconds to wait for the browser to come back from the consent screen
+# Token endpoint errors that mean the OAuth client itself is gone or unknown.
+CLIENT_GONE = {"invalid_client", "deleted_client"}
+
+
+def _missing_client_error() -> SetupError:
+    return SetupError(
+        f"No OAuth client file at {config.credentials_path()}. Run: gmail-agent setup. It "
+        "walks you through creating a Desktop OAuth client in Google Cloud, installs it and "
+        f"logs in. {SETUP_HINT}"
+    )
+
+
+def client_project() -> str | None:
+    """The Google Cloud project of the installed OAuth client, for console links."""
+    try:
+        data = json.loads(config.credentials_path().read_text())
+    except (OSError, ValueError):
+        return None
+    installed = data.get("installed") if isinstance(data, dict) else None
+    return installed.get("project_id") if isinstance(installed, dict) else None
+
+
+def console_url(path: str, project: str | None = None) -> str:
+    project = project or client_project()
+    return f"{CONSOLE}{path}" + (f"?project={project}" if project else "")
+
+
+def _client_gone() -> SetupError:
+    return SetupError(
+        f"Google no longer accepts the OAuth client in {config.credentials_path()}: it was "
+        "deleted, or unused for six months. Create a new one: run gmail-agent setup."
+    )
+
+
+def token_rejected(e: RefreshError) -> SetupError:
+    data = e.args[1] if len(e.args) > 1 and isinstance(e.args[1], dict) else {}
+    if data.get("error") in CLIENT_GONE:
+        return _client_gone()
+    return SetupError(
+        f"Google rejected the saved token ({e}). Run: gmail-agent login. If this happens "
+        "every 7 days, your OAuth app is in Testing mode; publish it (status 'In production') "
+        f"at {console_url('/auth/audience')}. {SETUP_HINT}"
+    )
+
+
+def _login_refused(e: Exception) -> SetupError:
+    """Errors from the consent flow (oauthlib's OAuth2Error has the OAuth error code)."""
+    code = getattr(e, "error", None)
+    if code in CLIENT_GONE:
+        return _client_gone()
+    if code == "access_denied":
+        return SetupError(
+            "Google did not grant access. Either the consent screen was cancelled, or the app "
+            "is in Testing mode and this address is not a test user. Add it under Test users, "
+            f"or publish the app, at {console_url('/auth/audience')}, then log in again."
+        )
+    description = getattr(e, "description", None) or str(e)
+    return SetupError(f"Google refused the login ({code}: {description}). {SETUP_HINT}")
+
+
+def granted_scopes(creds: Credentials) -> list[str]:
+    """What the user actually ticked on the consent screen (they can untick scopes)."""
+    granted = creds.granted_scopes or creds.scopes or []
+    return granted.split() if isinstance(granted, str) else list(granted)
+
+
+def login(level: str = config.DEFAULT_LEVEL, open_browser: bool = True) -> Credentials:
+    """Run the browser consent flow and save the token. Needs credentials.json."""
+    from google_auth_oauthlib.flow import InstalledAppFlow, WSGITimeoutError
+    from oauthlib.oauth2.rfc6749.errors import OAuth2Error
+
+    if level not in config.LEVELS:
+        raise GmailAgentError(
+            f"Unknown scope level {level!r}. Use one of: {', '.join(config.LEVELS)}"
+        )
+    client = config.credentials_path()
+    if not client.exists():
+        raise _missing_client_error()
+    try:
+        flow = InstalledAppFlow.from_client_secrets_file(str(client), config.LEVELS[level])
+    except (ValueError, json.JSONDecodeError) as e:
+        raise SetupError(
+            f"{client} is not a valid OAuth client file ({e}). Download the JSON for a client "
+            f"of type 'Desktop app'. {SETUP_HINT}"
+        ) from e
+    # The flow prints the login URL; keep it on stderr so `--json` output stays clean.
+    with contextlib.redirect_stdout(sys.stderr):
+        try:
+            creds = flow.run_local_server(
+                port=0,
+                open_browser=open_browser,
+                authorization_prompt_message="Open this URL in a browser to log in:\n{url}",
+                success_message="gmail-agent is logged in. You can close this tab.",
+                timeout_seconds=LOGIN_TIMEOUT,
+            )
+        except WSGITimeoutError as e:
+            raise SetupError(
+                f"The browser did not come back within {LOGIN_TIMEOUT // 60} minutes. Run "
+                "gmail-agent login again and finish the consent screen. If Google showed "
+                "'Access blocked', add your address as a test user or publish the app at "
+                f"{console_url('/auth/audience')}."
+            ) from e
+        except OAuth2Error as e:
+            raise _login_refused(e) from e
+    save_token(creds, scopes=granted_scopes(creds))
+    return creds
+
+
+def save_token(creds: Credentials, scopes: list[str] | None = None) -> Path:
+    """Write the token with owner-only permissions (0600), replacing any old one atomically.
+
+    Each save writes its own temporary file, so two processes refreshing at the same time
+    (the CLI and an MCP server, say) cannot leave a half-written token behind.
+    """
+    data = json.loads(creds.to_json())
+    if scopes is not None:
+        data["scopes"] = scopes
+    return write_private(config.token_path(), json.dumps(data))
+
+
+def write_private(path: Path, text: str) -> Path:
+    """Write `text` readable by the owner only (0600, in a 0700 folder), replacing `path`
+    atomically through a temporary file of its own."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    os.chmod(path.parent, 0o700)
+    fd, tmp = tempfile.mkstemp(dir=path.parent, prefix=f".{path.stem}-", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w") as f:
+            f.write(text)
+        os.replace(tmp, path)
+    except BaseException:
+        with contextlib.suppress(OSError):
+            os.unlink(tmp)
+        raise
+    return path
+
+
+def logout() -> bool:
+    """Delete the saved token. Returns False if there was none."""
+    path = config.token_path()
+    if not path.exists():
+        return False
+    path.unlink()
+    return True
+
+
+def saved_scopes() -> list[str] | None:
+    """The scopes recorded in the saved token, without touching the network. None if there is
+    no readable token."""
+    try:
+        scopes = json.loads(config.token_path().read_text()).get("scopes")
+    except (OSError, ValueError):
+        return None
+    return scopes.split() if isinstance(scopes, str) else scopes
+
+
+def load_credentials() -> Credentials:
+    """Load the saved token, refreshing it if needed. Never opens a browser."""
+    path = config.token_path()
+    if not path.exists():
+        if not config.credentials_path().exists():
+            raise _missing_client_error()
+        raise SetupError(f"Not logged in (no token at {path}). Run: gmail-agent login")
+    try:
+        creds = Credentials.from_authorized_user_file(str(path))
+    except (ValueError, json.JSONDecodeError) as e:
+        raise SetupError(f"Token file {path} is unreadable ({e}). Run: gmail-agent login") from e
+
+    if not creds.valid:
+        if not creds.refresh_token:
+            raise SetupError(f"Token at {path} has no refresh token. Run: gmail-agent login")
+        try:
+            creds.refresh(Request())
+        except RefreshError as e:
+            raise token_rejected(e) from e
+        except TransportError as e:
+            raise SetupError(f"Could not reach Google to refresh the token: {e}") from e
+        save_token(creds)
+    return creds
+
+
+def build_service(creds: Credentials, transport: Callable[[], Any] | None = None):
+    """The Gmail API service, safe to use from several threads at once.
+
+    httplib2 is not thread-safe, and the MCP server runs tool calls in worker threads, so
+    sharing one connection crashes the process when calls overlap. Every thread gets its own
+    authorized connection instead (google-api-python-client's documented requestBuilder
+    pattern). `transport` makes the plain httplib2.Http for each thread; tests replace it.
+    """
+    import google_auth_httplib2
+    from googleapiclient.discovery import build
+    from googleapiclient.http import HttpRequest, build_http
+
+    new_transport = transport or build_http
+    local = threading.local()
+
+    def thread_http() -> google_auth_httplib2.AuthorizedHttp:
+        if not hasattr(local, "http"):
+            local.http = google_auth_httplib2.AuthorizedHttp(creds, http=new_transport())
+        return local.http
+
+    def request_builder(_http, *args, **kwargs) -> HttpRequest:
+        return HttpRequest(thread_http(), *args, **kwargs)
+
+    return build(
+        "gmail", "v1", http=thread_http(), requestBuilder=request_builder, cache_discovery=False
+    )