gdrives 0.5.8__tar.gz

gdrives-0.5.8/.gitignore

@@ -0,0 +1,22 @@
+.archive/
+.claude/
+.hypothesis/
+.pytest_cache/
+.ruff_cache/
+.venv/
+.vscode/
+.worktrees/
+
+__pycache__/
+build/
+dist/
+*.egg-info/
+
+.DS_Store
+
+.coverage
+.coverage.*
+
+.env
+.env.*
+!.env.example

gdrives-0.5.8/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Added
+
+### Changed
+
+### Deprecated
+
+### Removed
+
+### Fixed
+
+### Security
+
+## [0.5.8] - 2026-06-09
+
+First release published to PyPI.
+
+### Added
+
+- PyPI publishing via GitHub Actions trusted publishing (OIDC), gated on the `PUBLISH_ENABLED` repository variable; `gdrives` is now installable from PyPI.
+
+## [0.5.7] - 2026-06-09
+
+### Changed
+
+- Renamed the package from `gdrive` to `gdrives` (module, CLI entry point, token/credential filenames, and cache directory).
+- Flattened the docs layout: guides moved from `docs/guides/` to `docs/`.

gdrives-0.5.8/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Ronald E. Robertson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

gdrives-0.5.8/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: gdrives
+Version: 0.5.8
+Project-URL: repository, https://github.com/gitronald/gdrives
+Author-email: gitronald <gitronald@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: google-api-python-client
+Requires-Dist: google-auth-oauthlib
+Requires-Dist: python-dotenv>=1.2.2
+Requires-Dist: typer
+Description-Content-Type: text/markdown
+
+# gdrives v0.5.8
+
+Command-line tools for Google Drive.
+
+Browse Google Drives, list folder contents by path or ID, export Google Docs,
+Sheets, and Slides to Office formats, download individual files or whole folder
+trees, and generate hyperlinked folder maps — all from the terminal.
+Human-readable Drive paths (e.g. `My Drive/projects`) resolve against a local
+drive-name cache, with first-class support for shared drives and "Shared with
+me" items. Listings carry URL, type, modified-date, owner, and sharer columns,
+and can be written as nested markdown or flat CSV from a single API traversal.
+Folder downloads scan and summarize before prompting, auto-exporting
+Google-native files and streaming binaries to disk with atomic writes.
+Authenticates via OAuth, a service account, or Application Default Credentials,
+and only ever requests read-only access (`drive.readonly`). Built on the
+[Google Drive API v3](https://developers.google.com/drive/api/reference/rest/v3)
+with a Typer CLI.
+
+## Project Structure
+
+```
+gdrives/
+├── cli.py       # Typer CLI: ls, export, download, show-drives
+├── auth.py      # OAuth, service-account, and ADC authentication
+├── drives.py    # Drive name→ID cache (fetch, save, resolve)
+├── resolve.py   # Path→ID resolution (drive paths and "shared with me")
+├── files.py     # Drive API wrappers: pagination, folder walk, file helpers
+├── listing.py   # DriveEntry, recursive collection, and table/markdown/CSV formatters
+├── export.py    # Export Google Docs, Sheets, and Slides to Office formats
+└── download.py  # Download a single file, or recurse a folder, to local disk
+```
+
+## Installation
+
+```bash
+uv tool install gdrives
+```
+
+As a project dependency:
+
+```bash
+uv add gdrives
+```
+
+From GitHub instead of PyPI:
+
+```bash
+uv tool install git+https://github.com/gitronald/gdrives.git
+# or, as a dependency: uv add git+https://github.com/gitronald/gdrives.git
+```
+
+From source (for development):
+
+```bash
+git clone https://github.com/gitronald/gdrives.git
+cd gdrives
+uv sync
+```
+
+The distribution and the installed command are both named `gdrives`.
+
+## Setup
+
+You need Google Drive API credentials before using `gdrives`. Pick the method
+that fits, follow its steps, then run `gdrives show-drives` to verify. Every
+method needs a Google Cloud project with the **Google Drive API** enabled;
+`gdrives` only ever requests read-only access (`drive.readonly`). When more than
+one is configured, authentication is attempted in order: OAuth, then service
+account, then ADC.
+
+### OAuth — personal use, interactive browser auth
+
+1. At [console.cloud.google.com](https://console.cloud.google.com), create or select a project, then enable the **Google Drive API** under **APIs & Services → Library**.
+2. Configure the **OAuth consent screen** (APIs & Services → OAuth consent screen): choose **External**, fill in app name and support email, leave it in **Testing**, and add your Google address under **Test users**.
+3. **Credentials → Create Credentials → OAuth client ID**, application type **Desktop app**, then download the JSON.
+4. Save it as `gdrives_credentials.json` in your config directory and export that path:
+   ```bash
+   export GOOGLE_CONFIG_DIR=~/.google   # directory holding gdrives_credentials.json
+   ```
+5. Run `gdrives show-drives`. A browser opens for one-time authorization; the token is cached to `$GOOGLE_CONFIG_DIR/gdrives_token.json` and reused (it re-auths automatically if revoked).
+
+Full walkthrough: [docs/setup-oauth.md](docs/setup-oauth.md).
+
+### Service account — automation, or sharing access with others
+
+1. Create or select a project and enable the **Google Drive API** (as above).
+2. **IAM & Admin → Service Accounts → Create Service Account**; give it a name like `drive-reader` and skip the optional grant steps.
+3. Open the new account's **Keys** tab → **Add Key → Create new key → JSON**, then download it.
+4. Save it as `service_account.json` in your config directory (or point `GOOGLE_SERVICE_ACCOUNT_PATH` at it):
+   ```bash
+   export GOOGLE_CONFIG_DIR=~/.google   # directory holding service_account.json
+   # or: export GOOGLE_SERVICE_ACCOUNT_PATH=/path/to/key.json
+   ```
+5. **Share** the target folder or shared drive with the service account's email (e.g. `drive-reader@your-project.iam.gserviceaccount.com`) as **Viewer** — it can only see what's explicitly shared with it.
+6. Run `gdrives show-drives`. No browser flow.
+
+Full walkthrough (key rotation, revoking access): [docs/setup-service-account.md](docs/setup-service-account.md).
+
+### gcloud / ADC — simplest if you already use the gcloud CLI
+
+1. Create or select a project and enable the **Google Drive API** (as above).
+2. Install the [gcloud CLI](https://cloud.google.com/sdk/docs/install) if you don't have it.
+3. Log in with the Drive scope — the `--scopes` flag is **required** (a plain login grants only `cloud-platform`, which excludes Drive and would 403):
+   ```bash
+   gcloud auth application-default login \
+     --scopes=https://www.googleapis.com/auth/drive.readonly,https://www.googleapis.com/auth/cloud-platform
+   ```
+4. Set a quota project (use the project where you enabled the Drive API):
+   ```bash
+   gcloud auth application-default set-quota-project YOUR_PROJECT_ID
+   ```
+5. Run `gdrives show-drives`. No `GOOGLE_CONFIG_DIR` and no credential files to manage.
+
+Full walkthrough: [docs/setup-adc.md](docs/setup-adc.md).
+
+## Configuration
+
+Set via environment variables or a `.env` file (env vars take precedence):
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `GOOGLE_CONFIG_DIR` | (required for OAuth; not needed for ADC) | Directory for the OAuth token and credentials |
+| `GOOGLE_SERVICE_ACCOUNT_PATH` | `$GOOGLE_CONFIG_DIR/service_account.json` | Service account key file |
+
+Authentication tries OAuth first, then the service account, then Application
+Default Credentials.
+
+## CLI Commands
+
+Run `gdrives show-drives` once to populate the drive-name cache
+(`.gdrives/cache.json`); the `ls` and `download` commands resolve Drive paths
+against it.
+
+### List Drive contents
+
+```bash
+gdrives ls                                              # My Drive (default)
+gdrives ls "My Drive/projects"                          # Subfolder
+gdrives ls "Shared drive name/subfolder"                # Shared drive
+gdrives ls "My Drive" --depth 2                         # Recurse deeper
+gdrives ls --drive-id <folder-id>                       # By folder ID
+gdrives ls --shared-with-me                             # Shared with me
+gdrives ls "Shared folder" --shared-with-me             # Shared subfolder
+```
+
+### Save a listing as markdown or CSV
+
+```bash
+gdrives ls "My Drive/projects" --save-as map.md         # Nested markdown
+gdrives ls "My Drive/projects" --save-as data.csv       # CSV export
+gdrives ls "My Drive/projects" --depth 3 --save-as map.md
+gdrives ls "My Drive/projects" --save-as map.md --save-as data.csv  # both, one traversal
+```
+
+### Export Google Docs, Sheets, and Slides
+
+```bash
+gdrives export <doc-url> -o output.docx     # Google Doc -> .docx
+gdrives export <sheet-url> -o output.xlsx   # Google Sheet -> .xlsx
+gdrives export <sheet-url> -o output.csv    # Google Sheet -> .csv (first tab only)
+gdrives export <slides-url> -o output.pptx  # Google Slides -> .pptx
+```
+
+### Download files and folders
+
+```bash
+gdrives download <file-url> -o ./out          # Single file -> ./out/<drive-name>
+gdrives download "My Drive/refs/paper.pdf"    # Single file by path -> ./paper.pdf
+gdrives download "My Drive/refs"              # Whole folder (recurses by default)
+gdrives download "My Drive/refs" --depth 1    # Folder, flat (no recursion)
+gdrives download "My Drive/refs" -y           # Skip the confirmation prompt
+```
+
+A source that resolves to a single file downloads immediately under its Drive
+name. A folder is scanned first, showing a summary, then prompts before
+downloading (`--depth` only affects folders). Google Docs, Sheets, and Slides
+auto-export to `.docx` / `.xlsx` / `.pptx`; other Google-native types (Forms,
+Drawings, etc.) are skipped.
+
+### Show available drives
+
+```bash
+gdrives show-drives
+```
+
+Output includes URL, type (personal/shared), name, and ID for each accessible
+drive, and is cached to `.gdrives/cache.json` for use by the other commands.
+
+## Related projects
+
+There are a few options out there, but most haven't been touched in years, and none did the mapping tasks implemented here.
+
+- [PyDrive2](https://github.com/iterative/PyDrive2) — fork of PyDrive, high-level Google Drive wrapper
+- [PyDrive](https://github.com/googlearchive/PyDrive) — the original high-level wrapper, now archived
+- [gdrive](https://pypi.org/project/gdrive/) "Simple Google Drive wrapper to traverse files"
+- [gdriver](https://pypi.org/project/gdriver/) "Actually usable Google Drive client"
+- [drive](https://pypi.org/project/drive/) "Google Drive client"
+
+## Security & privacy
+
+- `gdrives` only ever requests **read-only** Drive access (`drive.readonly`); it never modifies or deletes anything in your Drive.
+- The cached OAuth token (`$GOOGLE_CONFIG_DIR/gdrives_token.json`) holds a long-lived refresh token and is written with owner-only `0600` permissions. Keep `gdrives_credentials.json` and `service_account.json` out of version control and shared locations.
+- `gdrives show-drives` writes `.gdrives/cache.json` with the names and IDs of every Drive you can access; it is gitignored by default — keep it out of shared locations.

gdrives-0.5.8/README.md

@@ -0,0 +1,203 @@
+# gdrives v0.5.8
+
+Command-line tools for Google Drive.
+
+Browse Google Drives, list folder contents by path or ID, export Google Docs,
+Sheets, and Slides to Office formats, download individual files or whole folder
+trees, and generate hyperlinked folder maps — all from the terminal.
+Human-readable Drive paths (e.g. `My Drive/projects`) resolve against a local
+drive-name cache, with first-class support for shared drives and "Shared with
+me" items. Listings carry URL, type, modified-date, owner, and sharer columns,
+and can be written as nested markdown or flat CSV from a single API traversal.
+Folder downloads scan and summarize before prompting, auto-exporting
+Google-native files and streaming binaries to disk with atomic writes.
+Authenticates via OAuth, a service account, or Application Default Credentials,
+and only ever requests read-only access (`drive.readonly`). Built on the
+[Google Drive API v3](https://developers.google.com/drive/api/reference/rest/v3)
+with a Typer CLI.
+
+## Project Structure
+
+```
+gdrives/
+├── cli.py       # Typer CLI: ls, export, download, show-drives
+├── auth.py      # OAuth, service-account, and ADC authentication
+├── drives.py    # Drive name→ID cache (fetch, save, resolve)
+├── resolve.py   # Path→ID resolution (drive paths and "shared with me")
+├── files.py     # Drive API wrappers: pagination, folder walk, file helpers
+├── listing.py   # DriveEntry, recursive collection, and table/markdown/CSV formatters
+├── export.py    # Export Google Docs, Sheets, and Slides to Office formats
+└── download.py  # Download a single file, or recurse a folder, to local disk
+```
+
+## Installation
+
+```bash
+uv tool install gdrives
+```
+
+As a project dependency:
+
+```bash
+uv add gdrives
+```
+
+From GitHub instead of PyPI:
+
+```bash
+uv tool install git+https://github.com/gitronald/gdrives.git
+# or, as a dependency: uv add git+https://github.com/gitronald/gdrives.git
+```
+
+From source (for development):
+
+```bash
+git clone https://github.com/gitronald/gdrives.git
+cd gdrives
+uv sync
+```
+
+The distribution and the installed command are both named `gdrives`.
+
+## Setup
+
+You need Google Drive API credentials before using `gdrives`. Pick the method
+that fits, follow its steps, then run `gdrives show-drives` to verify. Every
+method needs a Google Cloud project with the **Google Drive API** enabled;
+`gdrives` only ever requests read-only access (`drive.readonly`). When more than
+one is configured, authentication is attempted in order: OAuth, then service
+account, then ADC.
+
+### OAuth — personal use, interactive browser auth
+
+1. At [console.cloud.google.com](https://console.cloud.google.com), create or select a project, then enable the **Google Drive API** under **APIs & Services → Library**.
+2. Configure the **OAuth consent screen** (APIs & Services → OAuth consent screen): choose **External**, fill in app name and support email, leave it in **Testing**, and add your Google address under **Test users**.
+3. **Credentials → Create Credentials → OAuth client ID**, application type **Desktop app**, then download the JSON.
+4. Save it as `gdrives_credentials.json` in your config directory and export that path:
+   ```bash
+   export GOOGLE_CONFIG_DIR=~/.google   # directory holding gdrives_credentials.json
+   ```
+5. Run `gdrives show-drives`. A browser opens for one-time authorization; the token is cached to `$GOOGLE_CONFIG_DIR/gdrives_token.json` and reused (it re-auths automatically if revoked).
+
+Full walkthrough: [docs/setup-oauth.md](docs/setup-oauth.md).
+
+### Service account — automation, or sharing access with others
+
+1. Create or select a project and enable the **Google Drive API** (as above).
+2. **IAM & Admin → Service Accounts → Create Service Account**; give it a name like `drive-reader` and skip the optional grant steps.
+3. Open the new account's **Keys** tab → **Add Key → Create new key → JSON**, then download it.
+4. Save it as `service_account.json` in your config directory (or point `GOOGLE_SERVICE_ACCOUNT_PATH` at it):
+   ```bash
+   export GOOGLE_CONFIG_DIR=~/.google   # directory holding service_account.json
+   # or: export GOOGLE_SERVICE_ACCOUNT_PATH=/path/to/key.json
+   ```
+5. **Share** the target folder or shared drive with the service account's email (e.g. `drive-reader@your-project.iam.gserviceaccount.com`) as **Viewer** — it can only see what's explicitly shared with it.
+6. Run `gdrives show-drives`. No browser flow.
+
+Full walkthrough (key rotation, revoking access): [docs/setup-service-account.md](docs/setup-service-account.md).
+
+### gcloud / ADC — simplest if you already use the gcloud CLI
+
+1. Create or select a project and enable the **Google Drive API** (as above).
+2. Install the [gcloud CLI](https://cloud.google.com/sdk/docs/install) if you don't have it.
+3. Log in with the Drive scope — the `--scopes` flag is **required** (a plain login grants only `cloud-platform`, which excludes Drive and would 403):
+   ```bash
+   gcloud auth application-default login \
+     --scopes=https://www.googleapis.com/auth/drive.readonly,https://www.googleapis.com/auth/cloud-platform
+   ```
+4. Set a quota project (use the project where you enabled the Drive API):
+   ```bash
+   gcloud auth application-default set-quota-project YOUR_PROJECT_ID
+   ```
+5. Run `gdrives show-drives`. No `GOOGLE_CONFIG_DIR` and no credential files to manage.
+
+Full walkthrough: [docs/setup-adc.md](docs/setup-adc.md).
+
+## Configuration
+
+Set via environment variables or a `.env` file (env vars take precedence):
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `GOOGLE_CONFIG_DIR` | (required for OAuth; not needed for ADC) | Directory for the OAuth token and credentials |
+| `GOOGLE_SERVICE_ACCOUNT_PATH` | `$GOOGLE_CONFIG_DIR/service_account.json` | Service account key file |
+
+Authentication tries OAuth first, then the service account, then Application
+Default Credentials.
+
+## CLI Commands
+
+Run `gdrives show-drives` once to populate the drive-name cache
+(`.gdrives/cache.json`); the `ls` and `download` commands resolve Drive paths
+against it.
+
+### List Drive contents
+
+```bash
+gdrives ls                                              # My Drive (default)
+gdrives ls "My Drive/projects"                          # Subfolder
+gdrives ls "Shared drive name/subfolder"                # Shared drive
+gdrives ls "My Drive" --depth 2                         # Recurse deeper
+gdrives ls --drive-id <folder-id>                       # By folder ID
+gdrives ls --shared-with-me                             # Shared with me
+gdrives ls "Shared folder" --shared-with-me             # Shared subfolder
+```
+
+### Save a listing as markdown or CSV
+
+```bash
+gdrives ls "My Drive/projects" --save-as map.md         # Nested markdown
+gdrives ls "My Drive/projects" --save-as data.csv       # CSV export
+gdrives ls "My Drive/projects" --depth 3 --save-as map.md
+gdrives ls "My Drive/projects" --save-as map.md --save-as data.csv  # both, one traversal
+```
+
+### Export Google Docs, Sheets, and Slides
+
+```bash
+gdrives export <doc-url> -o output.docx     # Google Doc -> .docx
+gdrives export <sheet-url> -o output.xlsx   # Google Sheet -> .xlsx
+gdrives export <sheet-url> -o output.csv    # Google Sheet -> .csv (first tab only)
+gdrives export <slides-url> -o output.pptx  # Google Slides -> .pptx
+```
+
+### Download files and folders
+
+```bash
+gdrives download <file-url> -o ./out          # Single file -> ./out/<drive-name>
+gdrives download "My Drive/refs/paper.pdf"    # Single file by path -> ./paper.pdf
+gdrives download "My Drive/refs"              # Whole folder (recurses by default)
+gdrives download "My Drive/refs" --depth 1    # Folder, flat (no recursion)
+gdrives download "My Drive/refs" -y           # Skip the confirmation prompt
+```
+
+A source that resolves to a single file downloads immediately under its Drive
+name. A folder is scanned first, showing a summary, then prompts before
+downloading (`--depth` only affects folders). Google Docs, Sheets, and Slides
+auto-export to `.docx` / `.xlsx` / `.pptx`; other Google-native types (Forms,
+Drawings, etc.) are skipped.
+
+### Show available drives
+
+```bash
+gdrives show-drives
+```
+
+Output includes URL, type (personal/shared), name, and ID for each accessible
+drive, and is cached to `.gdrives/cache.json` for use by the other commands.
+
+## Related projects
+
+There are a few options out there, but most haven't been touched in years, and none did the mapping tasks implemented here.
+
+- [PyDrive2](https://github.com/iterative/PyDrive2) — fork of PyDrive, high-level Google Drive wrapper
+- [PyDrive](https://github.com/googlearchive/PyDrive) — the original high-level wrapper, now archived
+- [gdrive](https://pypi.org/project/gdrive/) "Simple Google Drive wrapper to traverse files"
+- [gdriver](https://pypi.org/project/gdriver/) "Actually usable Google Drive client"
+- [drive](https://pypi.org/project/drive/) "Google Drive client"
+
+## Security & privacy
+
+- `gdrives` only ever requests **read-only** Drive access (`drive.readonly`); it never modifies or deletes anything in your Drive.
+- The cached OAuth token (`$GOOGLE_CONFIG_DIR/gdrives_token.json`) holds a long-lived refresh token and is written with owner-only `0600` permissions. Keep `gdrives_credentials.json` and `service_account.json` out of version control and shared locations.
+- `gdrives show-drives` writes `.gdrives/cache.json` with the names and IDs of every Drive you can access; it is gitignored by default — keep it out of shared locations.

gdrives-0.5.8/gdrives/auth.py

@@ -0,0 +1,161 @@
+"""Shared Google Drive authentication and service builder."""
+
+import logging
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+import google.auth.exceptions
+from dotenv import load_dotenv
+
+load_dotenv()
+
+logger = logging.getLogger(__name__)
+
+SCOPES = ["https://www.googleapis.com/auth/drive.readonly"]
+
+NO_CREDENTIALS_MESSAGE = (
+    "Error: no Google Drive credentials found. Set up one of:\n"
+    "  - OAuth: put gdrives_credentials.json in $GOOGLE_CONFIG_DIR "
+    "(docs/setup-oauth.md)\n"
+    "  - Service account: set GOOGLE_SERVICE_ACCOUNT_PATH, or put "
+    "service_account.json in $GOOGLE_CONFIG_DIR "
+    "(docs/setup-service-account.md)\n"
+    "  - gcloud/ADC: run 'gcloud auth application-default login "
+    "--scopes=https://www.googleapis.com/auth/drive.readonly' "
+    "(docs/setup-adc.md)"
+)
+
+
+def _config_dir() -> Path | None:
+    """Return the credentials directory, or None if GOOGLE_CONFIG_DIR is unset."""
+    value = os.environ.get("GOOGLE_CONFIG_DIR")
+    return Path(value) if value else None
+
+
+def _token_path() -> Path | None:
+    config_dir = _config_dir()
+    return config_dir / "gdrives_token.json" if config_dir else None
+
+
+def _credentials_path() -> Path | None:
+    config_dir = _config_dir()
+    return config_dir / "gdrives_credentials.json" if config_dir else None
+
+
+def _service_account_path() -> Path | None:
+    value = os.environ.get("GOOGLE_SERVICE_ACCOUNT_PATH")
+    if value:
+        return Path(value)
+    config_dir = _config_dir()
+    return config_dir / "service_account.json" if config_dir else None
+
+
+def _is_interactive() -> bool:
+    """True when stdin is a TTY, i.e. an interactive OAuth browser flow can run."""
+    return sys.stdin.isatty()
+
+
+def _write_token(token_path: Path, creds: Any) -> None:
+    """Persist OAuth credentials atomically with owner-only (0600) permissions.
+
+    The token file holds a long-lived refresh token, so it must not be group- or
+    world-readable. Writing through a 0600 temp file and an atomic rename avoids
+    both a loose-permission window and a partially written token on failure. A
+    failed write is logged, not raised — the caller still holds valid in-memory
+    credentials for this run.
+    """
+    try:
+        tmp = token_path.with_name(token_path.name + ".tmp")
+        fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        with os.fdopen(fd, "w") as f:
+            f.write(creds.to_json())
+        tmp.replace(token_path)
+    except OSError:
+        logger.warning("could not persist OAuth token to %s", token_path)
+
+
+def authenticate_oauth():
+    """Authenticate with Google Drive via OAuth client secrets flow.
+
+    Returns None when OAuth is not configured (GOOGLE_CONFIG_DIR unset, no client
+    secrets file, or no interactive terminal to complete the browser flow), so
+    authenticate() can fall through to other methods.
+    """
+    token_path = _token_path()
+    credentials_path = _credentials_path()
+    if token_path is None or credentials_path is None:
+        return None
+
+    from google.auth.transport.requests import Request
+    from google.oauth2.credentials import Credentials
+    from google_auth_oauthlib.flow import InstalledAppFlow
+
+    creds = None
+    if token_path.exists():
+        creds = Credentials.from_authorized_user_file(str(token_path), SCOPES)
+    if creds and creds.expired and creds.refresh_token:
+        try:
+            creds.refresh(Request())
+        except google.auth.exceptions.RefreshError:
+            creds = None
+        else:
+            _write_token(token_path, creds)
+    if not creds or not creds.valid:
+        # Fall through to other auth methods rather than blocking on a browser
+        # flow when there's no client secrets file or no interactive terminal.
+        if not credentials_path.exists() or not _is_interactive():
+            return None
+        flow = InstalledAppFlow.from_client_secrets_file(str(credentials_path), SCOPES)
+        creds = flow.run_local_server(port=0, open_browser=False)
+        _write_token(token_path, creds)
+    return creds
+
+
+def authenticate_service_account():
+    """Authenticate with Google Drive via a service account key file.
+
+    Returns None when no key file is configured or present.
+    """
+    from google.oauth2.service_account import Credentials
+
+    sa_path = _service_account_path()
+    if sa_path is None or not sa_path.exists():
+        return None
+    return Credentials.from_service_account_file(str(sa_path), scopes=SCOPES)
+
+
+def authenticate_adc():
+    """Authenticate with Google Drive via Application Default Credentials."""
+    import google.auth
+
+    creds, _ = google.auth.default(scopes=SCOPES)
+    return creds
+
+
+def authenticate():
+    """Authenticate with Google Drive.
+
+    Tries OAuth, then a service account key, then Application Default
+    Credentials (e.g. `gcloud auth application-default login`). Raises a
+    helpful SystemExit if none are configured.
+    """
+    creds = authenticate_oauth()
+    if creds:
+        return creds
+    creds = authenticate_service_account()
+    if creds:
+        return creds
+    try:
+        return authenticate_adc()
+    except google.auth.exceptions.GoogleAuthError:
+        raise SystemExit(NO_CREDENTIALS_MESSAGE)
+
+
+def build_drive_service():
+    """Authenticate and return a Drive v3 service."""
+    from googleapiclient.discovery import build
+
+    creds = authenticate()
+    return build("drive", "v3", credentials=creds)