Skip to content

feat(auth): add --extra-scopes flag for fine-grained custom OAuth scope selection #420

Closed

Description

@peteradams2026

Problem

Currently, gog auth add only allows scope selection via predefined service bundles (--services) and coarse-grained toggles (--readonly, --drive-scope, --gmail-scope). This makes it impossible to compose mixed permission sets like:

  • gmail.readonly (read emails) + gmail.labels (manage labels only) — without granting full gmail.modify
  • calendar.readonly (read events) + calendar.calendarlist (manage calendar subscriptions) — without full calendar
  • drive.readonly + drive.metadata (organize folders) — without full drive

This is a real pain point for AI assistant use cases where least-privilege access matters: you want the agent to read emails and manage labels, but absolutely not be able to send or delete anything.

Proposed Solution

Add an --extra-scopes flag (or --scopes) that accepts a comma-separated list of raw Google API scope URIs to append to the scopes derived from --services:

# Read emails only, but also allow managing labels
gog auth add user@example.com \
  --services gmail \
  --gmail-scope=readonly \
  --extra-scopes="https://www.googleapis.com/auth/gmail.labels"

# Read calendar, but allow managing calendar list subscriptions
gog auth add user@example.com \
  --services calendar \
  --readonly \
  --extra-scopes="https://www.googleapis.com/auth/calendar.calendarlist"

Resulting scopes would be:

https://www.googleapis.com/auth/gmail.readonly   ← from --gmail-scope=readonly
https://www.googleapis.com/auth/gmail.labels     ← from --extra-scopes

Why Not Just Expose Per-Service Scope Flags?

The --gmail-scope approach (PR #113) is great for binary full/readonly choices. But Google's API surface has dozens of granular sub-scopes per service (e.g., calendar.events.readonly, calendar.calendarlist, calendar.freebusy, drive.metadata.readonly, drive.activity.readonly, gmail.labels, etc.). Maintaining a separate flag for each is not scalable.

An --extra-scopes escape hatch gives power users full control without the maintenance burden.

References

Use Case (Real World)

I'm using gog with an AI assistant (OpenClaw) that manages my Google Workspace. I want to grant:

Service Read Write
Gmail ✅ gmail.readonly ✅ gmail.labels only
Calendar ✅ calendar.readonly ✅ calendar.calendarlist (subscribe/unsubscribe)
Drive ✅ drive.readonly ✅ drive.metadata (organize into folders)

This is currently impossible without granting broader scopes (gmail.modify, calendar, drive) and relying on the tool's self-restraint — which is not a real security boundary.

Thank you for this excellent tool! 🙏

Activity

  1. steipete commented on Apr 27, 2026

    @steipete
    Collaborator

    Fixed on current main. gog auth add supports --extra-scopes and remote auth guidance preserves it for step 2.

    Proof on main:

    • internal/cmd/auth_add.go has the ExtraScopes flag and scope append handling.
    • Focused test gate passed, including TestAuthAddCmd_ExtraScopes and remote step guidance coverage.

    Closing as completed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    Priority

    None yet

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions