Skip to content

feat(auth): add Gmail read-send scope - #1033

Merged
steipete merged 2 commits into
openclaw:mainfrom
higginz777:codex/gmail-read-send-scope
Aug 25, 2026
Merged

steipete merged 2 commits into
openclaw:mainfrom
higginz777:codex/gmail-read-send-scope

Conversation

@higginz777

Copy link
Copy Markdown
Contributor

Summary

  • add --gmail-scope read-send requesting exactly Gmail readonly + send access
  • retain mandatory OpenID identity scopes
  • disable incremental authorization for limited-scope auth and automatic reauthorization, including stored-token scope paths
  • preserve existing full and readonly behavior

Why

Clients that search and send mail should not need Gmail modify/settings permissions. This preset provides least-privilege read-and-send authorization and ensures reauthorization does not silently retain broader prior grants.

Tests

  • make ci
  • lint: 0 issues
  • all Go and Node tests passed
  • 728 command pages generated; docs build, link tests, and coverage passed
  • regression coverage includes CLI parsing, exact scope selection, limited-scope incremental-auth behavior, and stored-scope reauthorization

User-facing changes

gog auth add --services gmail --gmail-scope read-send now requests Gmail read and send access without Gmail modify/settings scopes.

@clawsweeper

clawsweeper Bot commented Aug 25, 2026

Copy link
Copy Markdown
Contributor

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

@higginz777
higginz777 marked this pull request as ready for review August 25, 2026 21:39
@clawsweeper clawsweeper Bot added merge-risk: 🚨 auth-provider 🚨 Merging this PR could break OAuth, tokens, provider routing, model choice, or credentials. P2 Normal priority bug or improvement with limited blast radius. rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. labels Aug 25, 2026
@clawsweeper

clawsweeper Bot commented Aug 25, 2026 •

Copy link
Copy Markdown
Contributor

Codex review: needs real behavior proof before merge. Reviewed August 25, 2026, 7:48 PM ET / 23:48 UTC.

ClawSweeper review

What this changes

Adds Gmail send and read-send scope presets and avoids incremental authorization when limited Gmail scopes are requested or reauthorized.

Merge readiness

⛔ Blocked until real behavior proof from a real setup is added - 3 items remain

This PR adds a still-missing least-privilege Gmail authorization mode. The implementation is focused and the follow-up hardening is sound, but real OAuth behavior proof remains required before merge.

Priority: P2
Reviewed head: 80157ea35049930ec5456a1d2508b5d6d40c3f53

Review scores

Measure Result What it means
Overall readiness 🧂 unranked krab (1/6) The patch is focused, but missing real OAuth authority proof is a merge gate.
Proof confidence 🧂 unranked krab (1/6) Needs real behavior proof before merge: Authority-chain proof required: unit coverage and CI claims do not prove that Google grants and reauthorizes only the intended limited scopes; add a redacted live authorization and recovery result before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Patch quality 🦐 gold shrimp (3/6) No actionable review findings were identified.

Verification

Check Result Evidence
Real behavior Needs proof Needs real behavior proof before merge: Authority-chain proof required: unit coverage and CI claims do not prove that Google grants and reauthorizes only the intended limited scopes; add a redacted live authorization and recovery result before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Evidence reviewed 6 items Current main lacks the feature: Current main accepts only full and readonly Gmail scope modes, so the requested send and read-send modes are not already implemented.
Exact limited scope mapping: The branch maps send to Gmail send only and read-send to Gmail readonly plus send, while the shared builder retains identity scopes.
Reauthorization safeguard: Stored limited Gmail grants disable include_granted_scopes, while grants containing broader Gmail permissions retain the existing incremental behavior.
Findings None None.
Security None None.

How this fits together

The auth command turns service and scope flags into a Google OAuth consent request, then records token metadata for recovery and reauthorization. Those scopes determine what Gmail operations the CLI can perform.

flowchart LR
  A[Auth command] --> B[Scope preset]
  B --> C[OAuth request]
  C --> D[Google consent]
  D --> E[Stored token]
  E --> F[Reauthorization]
  F --> G[Gmail access]
Loading

Before merge

  • Add real behavior proof - Needs real behavior proof before merge: Authority-chain proof required: unit coverage and CI claims do not prove that Google grants and reauthorizes only the intended limited scopes; add a redacted live authorization and recovery result before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
  • Resolve merge risk (P1) - The changed OAuth authority path lacks final-effect proof that a limited grant and its reauthorization do not retain broader historical Gmail permissions.
  • Complete next step (P2) - A contributor must supply real OAuth proof before a human merge decision; this cannot be safely repaired by automation.
Agent review details

Security

None.

Review metrics

Metric Value Why it matters
Change surface 12 files; production +72, tests +284, docs +9 The OAuth behavior change has substantial focused regression coverage across command, scope, URL, and reauthorization paths.

Merge-risk options

Maintainer options:

  1. Add live limited-scope proof (recommended)
    Provide redacted evidence of a fresh limited grant and subsequent reauthorization showing the intended Gmail scopes remain limited.

Technical review

Best possible solution:

Land the explicit scope presets only after redacted live Google consent and reauthorization evidence confirms the requested limited scopes and successful recovery path.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a defect reproduction; the outstanding need is a real after-fix OAuth authorization and reauthorization demonstration, not another mocked test.

Is this the best way to solve the issue?

Yes, conditionally: the preset and exact-scope approach is narrow and covered in source, but live OAuth proof is needed to validate its authorization-boundary claim.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 4f4216bafd6c.

Labels

Label changes:

  • add rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🦐 gold shrimp.
  • remove rating: 🦪 silver shellfish: Current PR rating is rating: 🧂 unranked krab, so this older rating label is no longer current.

Label justifications:

  • P2: This is a bounded new OAuth authorization mode without evidence of an urgent existing-user failure.
  • merge-risk: 🚨 auth-provider: The PR changes Gmail consent scopes and stored-token reauthorization behavior.
  • rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🦐 gold shrimp.
  • status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: Authority-chain proof required: unit coverage and CI claims do not prove that Google grants and reauthorizes only the intended limited scopes; add a redacted live authorization and recovery result before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence

What I checked:

  • Current main lacks the feature: Current main accepts only full and readonly Gmail scope modes, so the requested send and read-send modes are not already implemented. (internal/googleauth/service.go:64, 4f4216bafd6c)
  • Exact limited scope mapping: The branch maps send to Gmail send only and read-send to Gmail readonly plus send, while the shared builder retains identity scopes. (internal/googleauth/service.go:566, 80157ea35049)
  • Reauthorization safeguard: Stored limited Gmail grants disable include_granted_scopes, while grants containing broader Gmail permissions retain the existing incremental behavior. (internal/googleauth/reauth.go:159, 80157ea35049)
  • OAuth authority boundary: The implementation passes the scope decision into every browser and manual OAuth URL construction path, so Google OAuth is the relevant external authorization contract. (internal/googleauth/oauth_flow.go:269, 80157ea35049)
  • Area provenance: Current main’s reauthorization implementation originates with the revoked-token recovery feature, authored by Peter Steinberger. (internal/googleauth/reauth.go:159, 229da12809c1)
  • Proof remains absent: The previous review requested redacted real authorization and recovery evidence; the supplied follow-up adds tests and hardening but no live OAuth artifact. (80157ea35049)

Likely related people:

  • steipete: Authored the current-main revoked-token recovery path and the follow-up hardening commit for this auth flow. (role: recent auth-area contributor; confidence: high; commits: 229da12809c1, 80157ea35049; files: internal/googleauth/reauth.go, internal/googleauth/service.go, internal/cmd/auth_add.go)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

  • Add a redacted real authorization result for read-send that shows the consent request excludes Gmail modify and settings access.
  • Add final-effect proof for the nearest unauthorized scope case and prove reauthorization of a limited stored grant remains limited before I/O.

Rating scale

Score Internal tier Crab rank Meaning
6/6 S 🦀 challenger crab Exceptional readiness
5/6 A 🦞 diamond lobster Very strong readiness
4/6 B 🐚 platinum hermit Good normal PR; ordinary maintainer review
3/6 C 🦐 gold shrimp Useful, but confidence is limited
2/6 D 🦪 silver shellfish Proof or implementation needs work
1/6 F 🧂 unranked krab Not merge-ready
N/A NA 🌊 off-meta tidepool Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

  • ClawSweeper keeps one durable marker-backed review comment per issue or PR.
  • Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
  • A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
  • PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
  • Maintainers can also comment @clawsweeper review to request a fresh review only.
  • Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
  • Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
  • Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (1 earlier review cycle)
  • reviewed 2026-08-25T21:44:45.160Z sha 2216afe :: needs real behavior proof before merge. :: none

@clawsweeper clawsweeper Bot added rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. and removed rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. labels Aug 25, 2026
@steipete
steipete merged commit c1a4191 into openclaw:main Aug 25, 2026
9 checks passed
@steipete

Copy link
Copy Markdown
Collaborator

Landed as c1a4191 after preserving the contributor commit and tightening the proposed scope boundary.

Verification:

  • make ci passed locally, including Go/Node tests, lint, dead-code checks, all 728 generated command pages, docs coverage, and generated agent skills.
  • Focused regressions cover exact send, read-send, readonly, and full scope sets; rejection of writable Gmail scopes under --readonly; Google OAuth URL/PKCE construction without incremental scope union; remote dry-runs without OAuth/keyring/state side effects; narrow-grant reauthorization; and imported tokens without stored scope metadata.
  • Built-CLI authorization previews were exercised for all four Gmail modes using --json --dry-run --no-input --remote; send-only emitted exactly gmail.send plus identity scopes, and no OAuth state or token was created.
  • A real read-only Gmail message search succeeded with the existing designated test account after the change; the account's existing token was not modified and no email was sent.
  • Exact-head hosted CI: https://github.com/openclaw/gogcli/actions/runs/32912137342 (Linux, Windows, macOS, and worker all green).
  • Exact-head hosted Docker: https://github.com/openclaw/gogcli/actions/runs/32912137355 (green).

A completed live consent/send cannot be demonstrated with the current test token because Google granted it only gmail.readonly; that provider-proof limitation remains explicit.

mcaldas added a commit to mcaldas/gogcli that referenced this pull request Sep 2, 2026
Upstream openclaw#1033 added --gmail-scope send and read-send. read-send is the right
grant for an account served with --allow-send: read and send without full
mailbox modify. Also note that any narrowed scope disables incremental
authorization, so a re-consent must name every service it wants.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KPDVDx9x2HsmoxjrYMRU3Y
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge-risk: 🚨 auth-provider 🚨 Merging this PR could break OAuth, tokens, provider routing, model choice, or credentials. P2 Normal priority bug or improvement with limited blast radius. rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants