Zero-config auth: work automatically when gws or gogcli is already set up

[sripathikrishnan]

Problem

Right now, every extrasuite user must go through a separate auth setup step — either install and configure a gateway server, or manually supply a service account JSON file. This friction is a barrier for users who are already authenticated with popular Google Workspace CLI tools like gws or gogcli, and just want to try the pull/diff/push workflow.

Desired behavior

extrasuite should resolve credentials in this order, automatically:

1. ExtraSuite server — if configured (via EXTRASUITE_SERVER_URL, --gateway, or ~/.config/extrasuite/gateway.json), use it. This gives you named agent identity and a full audit trail. Recommended for team deployments.

2. Service account file — if SERVICE_ACCOUNT_PATH or --service-account is set, use the SA key directly.

3. gws — if the user has configured gws, extrasuite picks up those credentials and authenticates against Google directly. No extra setup required. Relevant environment variables/files: GOOGLE_WORKSPACE_CLI_TOKEN, GOOGLE_WORKSPACE_CLI_CLIENT_ID + GOOGLE_WORKSPACE_CLI_CLIENT_SECRET, GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE, ~/.config/gws/client_secret.json.

4. gogcli — same idea for gogcli users. Relevant config: GOG_ACCESS_TOKEN, ~/.config/gogcli/credentials.json (platform-specific path).

5. Fail with a clear error message listing what to configure.

What "works automatically" means

• If a pre-obtained access token is available (GOOGLE_WORKSPACE_CLI_TOKEN / GOG_ACCESS_TOKEN), use it immediately — no browser needed.
• If OAuth client credentials are found (client ID + secret from gws or gogcli config), extrasuite performs a one-time OAuth browser flow using those credentials, stores the resulting refresh token in its own secure keyring entry, and silently refreshes it on every subsequent run. The user sees a standard Google consent screen the first time only.

Trade-offs vs. the gateway

In gws/gogcli mode, operations happen under the user's own Google identity (the same account they used when setting up gws/gogcli). File edits in Google Drive will show as made by that person, not a named agent. For personal use and experimentation this is fine. Teams who want a distinct agent identity and strong audit trail should still configure the gateway server.

Scope of this issue

• Layered credential resolution in CredentialsManager
• Reading gws and gogcli credential files from their documented, public config locations
• One-time OAuth dance using the discovered client credentials, with refresh token stored in extrasuite's own keyring
• Clear, actionable error messages when no auth method is found, including hints about what to configure

[sripathikrishnan]

Implementation Plan: Zero-Config Auth for gws and gogcli Users

Related issue: #70

Goal

A layered credential resolution system so that users who already have gws or gogcli configured can run extrasuite commands without any additional setup. The ExtraSuite gateway server remains the first choice when configured — it provides named agent identity and a full audit trail.

---

Resolution Order

1. ExtraSuite server      configured via EXTRASUITE_SERVER_URL, --gateway, or gateway.json
2. Service account file   --service-account flag or SERVICE_ACCOUNT_PATH env var
3. Bare access token      GOOGLE_WORKSPACE_CLI_TOKEN (gws) or GOG_ACCESS_TOKEN (gogcli)
4. gws OAuth client       client credentials from gws config → one-time browser flow
5. gogcli OAuth client    client credentials from gogcli config → one-time browser flow
6. Fail                   actionable error listing all options

Layers 1–2 are unchanged. This plan adds layers 3–5 and improves the layer-6 error message.

---

New Concepts

OAuthClientCredentials dataclass

@dataclass
class OAuthClientCredentials:
    client_id: str
    client_secret: str
    source: str  # "gws" | "gogcli" — used only in log/error messages

New Credential.kind value: "bearer_oauth_user"

Indicates a short-lived Google access token issued directly to the user's Google account (as opposed to a service account or domain-wide delegation token). The extra* libraries treat it identically — they only need cred.token.

New CredentialsManager._auth_mode values

Alongside the existing "extrasuite" and "service_account":

• "bare_token" — a pre-obtained access token from an env var; used immediately, no refresh possible.
• "oauth_client" — extrasuite holds an OAuth client ID + secret from gws/gogcli config, manages its own refresh token in its own keyring entry.

---

Step 1 — Credential Discovery Functions

File: client/src/extrasuite/client/credentials.py

Two new module-level functions. Pure: no side effects, no network, no browser.

_find_gws_client_credentials() -> OAuthClientCredentials | None

Checks in order:

1. GOOGLE_WORKSPACE_CLI_CLIENT_ID + GOOGLE_WORKSPACE_CLI_CLIENT_SECRET env vars — use directly.
2. GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE env var — read the file:
   • If it is a service account JSON ("type": "service_account"), skip (handled by layer 2 already).
   • If it is an OAuth client JSON (installed.client_id / web.client_id), extract credentials.
3. ~/.config/gws/client_secret.json — same OAuth client JSON parse.

Returns None if none of the above yield a client_id + client_secret.

_find_gogcli_client_credentials() -> OAuthClientCredentials | None

Checks:

1. ~/.config/gogcli/credentials.json on Linux (respects XDG_CONFIG_HOME).
2. ~/Library/Application Support/gogcli/credentials.json on macOS.
3. %APPDATA%\gogcli\credentials.json on Windows.

gogcli stores credentials in a flat format: {"client_id": "...", "client_secret": "..."}.

Returns None if the file does not exist or cannot be parsed.

OAuth client JSON parsing

Both functions share a helper that handles the standard Google Desktop app format:

{"installed": {"client_id": "...", "client_secret": "..."}}

as well as the web key variant, and gogcli's flat {"client_id": "...", "client_secret": "..."} format.

---

Step 2 — Direct Google Token Exchange

File: client/src/extrasuite/client/credentials.py

_exchange_refresh_token(client_id, client_secret, refresh_token) -> tuple[str, float]

POSTs to https://oauth2.googleapis.com/token with grant_type=refresh_token. Returns (access_token, expires_at_unix_timestamp). Uses the existing urllib.request + SSL_CONTEXT pattern already in this file — no new dependencies.

_run_oauth_browser_flow(client_id, client_secret, scopes, *, headless) -> tuple[str, str]

A standard OAuth 2.0 authorization code flow:

1. Generates a state nonce and a PKCE code_verifier / code_challenge.
2. Builds the Google authorization URL: https://accounts.google.com/o/oauth2/v2/auth.
3. Reuses the existing localhost callback server from _run_browser_flow_for_session().
4. Exchanges the code at https://oauth2.googleapis.com/token with grant_type=authorization_code.
5. Returns (access_token, refresh_token).

The key difference from today's browser flow: the code exchange calls Google's token endpoint directly instead of the extrasuite server endpoint.

Scopes requested:

_OAUTH_USER_SCOPES = [
    "https://www.googleapis.com/auth/spreadsheets",
    "https://www.googleapis.com/auth/documents",
    "https://www.googleapis.com/auth/presentations",
    "https://www.googleapis.com/auth/drive.file",
    "https://www.googleapis.com/auth/forms.body",
    "openid",
    "email",
]

---

Step 3 — Refresh Token Storage

The existing KeyringSessionStore stores a SessionToken(raw_token, email, expires_at). The raw_token field is an opaque string — we reuse this to store the Google refresh token.

Storage keys (profile names passed to KeyringSessionStore):

Source	Profile key
gws	"gws-default"
gogcli	"gogcli-default"

This is isolated from extrasuite server profiles ("default", "work", etc.) by the distinct key names. No new storage class is needed.

---

Step 4 — CredentialsManager.__init__ Resolution Chain

File: client/src/extrasuite/client/credentials.py

Replace the current ValueError (thrown when neither server nor SA is configured, at the bottom of __init__) with the new resolution chain.

# Layer 3: bare access token
bare = (
    os.environ.get("GOOGLE_WORKSPACE_CLI_TOKEN")
    or os.environ.get("GOG_ACCESS_TOKEN")
)
if bare:
    self._auth_mode = "bare_token"
    self._bare_token = bare
    return

# Layer 4: gws OAuth client
creds = _find_gws_client_credentials()
if creds:
    self._auth_mode = "oauth_client"
    self._oauth_client_creds = creds
    return

# Layer 5: gogcli OAuth client
creds = _find_gogcli_client_credentials()
if creds:
    self._auth_mode = "oauth_client"
    self._oauth_client_creds = creds
    return

# Layer 6: nothing found
raise ValueError(_NO_AUTH_MESSAGE)

New instance variables introduced:

Variable	Type	Set when
_auth_mode	str	always
_bare_token	str | None	"bare_token" mode
_oauth_client_creds	OAuthClientCredentials | None	"oauth_client" mode

---

Step 5 — get_credential() Dispatch

File: client/src/extrasuite/client/credentials.py

Add two new branches alongside the existing "extrasuite" and "service_account" branches.

"bare_token" branch

return Credential(
    provider="google",
    kind="bearer_oauth_user",
    token=self._bare_token,
    expires_at=time.time() + 3500,  # ~1 h; no way to know exact expiry
    scopes=[],
    metadata={},
)

"oauth_client" branch — _get_oauth_client_credential()

def _get_oauth_client_credential(self) -> Credential:
    creds = self._oauth_client_creds   # always non-None in this mode
    profile = f"{creds.source}-default"

    # Try cached refresh token
    stored = self._load_session_token(profile)
    if stored:
        try:
            access_token, expires_at = _exchange_refresh_token(
                creds.client_id, creds.client_secret, stored.raw_token
            )
            return Credential(provider="google", kind="bearer_oauth_user",
                              token=access_token, expires_at=expires_at,
                              scopes=[], metadata={})
        except Exception:
            # Refresh token revoked or expired — fall through to re-auth
            self._delete_session_token(profile)

    # No valid refresh token — do browser flow
    access_token, refresh_token = _run_oauth_browser_flow(
        creds.client_id, creds.client_secret,
        _OAUTH_USER_SCOPES, headless=self._headless,
    )
    self._save_session_token(
        SessionToken(
            raw_token=refresh_token,
            email="",
            expires_at=time.time() + 30 * 86400,
        ),
        profile,
    )
    return Credential(
        provider="google", kind="bearer_oauth_user",
        token=access_token, expires_at=time.time() + 3500,
        scopes=[], metadata={},
    )

---

Step 6 — Error Message

Replace the current ValueError message with:

No authentication method found.

extrasuite checks for credentials in this order:

  1. ExtraSuite gateway
       EXTRASUITE_SERVER_URL env var
       --gateway /path/to/gateway.json
       ~/.config/extrasuite/gateway.json

  2. Service account file
       --service-account /path/to/sa.json
       SERVICE_ACCOUNT_PATH env var

  3. gws (pre-obtained token)
       GOOGLE_WORKSPACE_CLI_TOKEN env var

  4. gws (OAuth client)
       GOOGLE_WORKSPACE_CLI_CLIENT_ID + GOOGLE_WORKSPACE_CLI_CLIENT_SECRET env vars
       GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE env var
       ~/.config/gws/client_secret.json

  5. gogcli (pre-obtained token)
       GOG_ACCESS_TOKEN env var

  6. gogcli (OAuth client)
       ~/.config/gogcli/credentials.json
       (~/Library/Application Support/gogcli/ on macOS)

Quick start options:
  Already use gws?    Run: gws auth setup   (then re-run your extrasuite command)
  Already use gogcli? Run: gog auth credentials <path/to/client_secret.json>
  Team deployment?    Run: extrasuite auth login   (requires gateway server)

---

Step 7 — _cmd_create Guard

File: client/src/extrasuite/client/cli/_common.py

_cmd_create() currently shares the newly created Google file with the service account email (cred.service_account_email). In "bearer_oauth_user" mode there is no SA email — the file is already owned by the user, so sharing is unnecessary.

Add a guard after file creation:

if cred.kind != "bearer_oauth_user":
    if not sa_email:
        raise RuntimeError("Could not determine service account email.")
    share_file(oauth_token_access, file_id, sa_email)
    print(f"Shared with: {sa_email}")
else:
    print("(File owned by your Google account — no sharing needed)")

---

Step 8 — auth status Update

File: client/src/extrasuite/client/cli/auth.py

The extrasuite auth status command currently only reports extrasuite server profiles. Extend it to show the active auth mode:

Active auth mode: oauth_client (gws)
  Client credentials: ~/.config/gws/client_secret.json
  Refresh token:      stored (gws-default profile)
  Run 'extrasuite auth login' to switch to ExtraSuite server mode.

For "bare_token" mode:

Active auth mode: bare_token (GOOGLE_WORKSPACE_CLI_TOKEN)
  Token expires:  ~55 minutes
  Note: token is not auto-refreshed. Re-export from gws to renew.

---

Files Changed

File	Nature of change
client/src/extrasuite/client/credentials.py	Core of the work — new dataclass, discovery functions, token exchange, browser flow, resolution chain
client/src/extrasuite/client/cli/_common.py	_cmd_create SA-sharing guard
client/src/extrasuite/client/cli/auth.py	status command — show new auth modes
client/CLAUDE.md	Update auth mode documentation
client/tests/test_credentials.py	Unit tests for discovery functions, token exchange (mocked HTTP), full oauth_client flow with a fake token server

---

Trade-offs and Limitations

Identity in Drive history: In oauth_client mode, edits appear under the user's own Google account, not a named agent. Organizations that need a distinct agent identity should configure the ExtraSuite gateway server (layer 1).

Scope coverage: The user must have authorized the required scopes when they set up gws/gogcli. If their existing OAuth consent only covers Gmail, Sheets API calls will return 403. extrasuite should detect this and print a targeted message — e.g., "Your token is missing the spreadsheets scope. Re-run the browser auth: extrasuite auth refresh --source gws".

gogcli credential file location: Follows XDG_CONFIG_HOME on Linux and os.UserConfigDir() on macOS/Windows — consistent with what gogcli itself does. The platform and os modules (already imported in credentials.py) are sufficient; no new dependencies.

Refresh token expiry: Google refresh tokens for Desktop app OAuth clients do not expire unless revoked or unused for 6+ months. The 30-day expires_at written to the SessionToken is a conservative local bound; extrasuite will re-auth after 30 days even if the refresh token is still valid. This is safe and predictable.

No new dependencies. All HTTP calls use urllib.request (already used throughout credentials.py). Keyring storage reuses the existing KeyringSessionStore. No new packages are added to pyproject.toml.

[mannykoum]

This doesn't work..