feat(gmail): support custom API endpoint

[sallyom]

Adds GOG_GMAIL_BASE_URL to route Gmail API requests through a compatible custom endpoint, such as a security proxy or test server.

The override applies to standard Gmail and batch-delete clients. Existing behavior is unchanged when the variable is unset.

Testing

• Added custom-endpoint coverage for Gmail service creation.
• Added command-level coverage for authenticated Gmail get and batch-delete requests.
• go test ./internal/googleapi
• make ci
• Built bin/gog and ran both command paths against a live loopback-compatible endpoint using a synthetic token and synthetic message identifiers. The endpoint logged only the request method/path and whether bearer authentication was present:

PROOF method=GET path=/gmail/v1/users/me/messages/proof-message authorization_present=true
PROOF method=POST path=/gmail/v1/users/me/messages/batchDelete authorization_present=true

No token value, mailbox content, or external Gmail account data was included in the proof.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

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

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed August 18, 2026, 3:09 PM ET / 19:09 UTC.

ClawSweeper review

What this changes

The PR adds GOG_GMAIL_BASE_URL, validates it as HTTPS or loopback HTTP, and routes regular and batch-delete Gmail API clients through that endpoint when set.

Merge readiness

⚠️ Ready for maintainer review - 4 items remain

Keep open for explicit maintainer approval: the implementation is sound, but it deliberately creates an opt-in boundary that sends OAuth-authenticated Gmail traffic to a configured endpoint.

Priority: P1
Reviewed head: 5699ae24b86de70a180a133e1b79c79acb1c74f4
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	The focused implementation, route coverage, and live loopback proof are good; explicit maintainer acceptance of the new trust boundary remains necessary.
Proof confidence	🐚 platinum hermit (4/6)	Sufficient (live_output): The PR body contains redacted after-fix live output showing authenticated Gmail get and batch-delete requests reaching a loopback-compatible endpoint.
Patch quality	🐚 platinum hermit (4/6)	Security review found an item that needs attention.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (live_output): The PR body contains redacted after-fix live output showing authenticated Gmail get and batch-delete requests reaching a loopback-compatible endpoint.
Evidence reviewed	6 items	Current main lacks this capability: Current main constructs the shared factory with only Photos endpoint overrides and its Gmail factory methods always use the default Gmail service endpoint. Scoped endpoint validation: The PR accepts only absolute HTTPS URLs or loopback HTTP URLs before adding the value to runtime setup. All intended Gmail client paths use the override: The shared factory applies the configured endpoint to both normal Gmail and batch-delete service construction; command runtime wiring uses these factory methods.
Findings	None	None.
Security	Needs attention	Approve the custom credential-bearing endpoint boundary: Setting this environment variable routes OAuth bearer credentials and Gmail request data to the selected endpoint; transport validation mitigates plaintext remote use but does not make the remote endpoint trusted.

How this fits together

Gmail commands obtain authenticated Google API services from the shared runtime factory. This setting changes the destination for those Gmail requests while leaving the default Google endpoint unchanged when unset.

flowchart LR
  A[Operator environment] --> B[Endpoint validation]
  B --> C[Runtime service setup]
  C --> D[Gmail service factory]
  D --> E[Authenticated Gmail commands]
  E --> F[Configured Gmail API endpoint]

Loading

Decision needed

Question	Recommendation
Should gogcli expose an operator-configured Gmail endpoint that receives OAuth bearer credentials and Gmail request data?	Accept the documented opt-in boundary: Merge the feature as an explicit operator-controlled HTTPS or local-development endpoint override.

Why: The code safely constrains transport and documents the consequence, but whether this trust boundary belongs in the supported product is a maintainer security and product decision.

Before merge

• Resolve security concern: Approve the custom credential-bearing endpoint boundary - Setting this environment variable routes OAuth bearer credentials and Gmail request data to the selected endpoint; transport validation mitigates plaintext remote use but does not make the remote endpoint trusted.
• Resolve merge risk (P1) - Merging creates an intentional trust boundary: a process that sets GOG_GMAIL_BASE_URL sends OAuth bearer credentials and Gmail request data to that HTTPS endpoint.
• Complete next step (P2) - A maintainer must explicitly accept or reject the new credential-routing boundary before this otherwise-correct feature can merge.

Findings

• [medium] Approve the custom credential-bearing endpoint boundary — internal/cmd/root.go:297

Agent review details

Security

Needs attention: The patch deliberately adds a credential-routing security boundary that needs maintainer acceptance, despite its HTTPS-or-loopback validation.

Review metrics

Metric	Value	Why it matters
Patch size	9 files changed; 185 additions, 5 deletions	Most of the patch is focused command and service coverage around a new credential-routing setting.

Merge-risk options

Maintainer options:

1. Accept the documented opt-in boundary (recommended)
   Approve merging the HTTPS-or-loopback override with its explicit warning that the endpoint receives OAuth bearer credentials and Gmail data.
2. Keep Gmail routing fixed
   Decline the setting if configurable credential-bearing Gmail endpoints are outside the supported security model.

Technical review

Best possible solution:

If a maintainer sponsors this opt-in proxy capability, retain the default Google endpoint, the HTTPS-or-loopback restriction, and the explicit credential-routing documentation.

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

Not applicable as a bug reproduction: this is new opt-in behavior, and the PR supplies a live loopback run covering both authenticated request paths.

Is this the best way to solve the issue?

Unclear: the implementation is narrow and validated, but only a maintainer can determine whether this credential-routing capability is an acceptable supported boundary.

AGENTS.md: found and applied where relevant.

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

Labels

Label justifications:

• P1: The PR changes the destination of OAuth-authenticated Gmail traffic, making the security-model decision urgent for affected operators.
• merge-risk: 🚨 security-boundary: A configured endpoint receives bearer credentials and Gmail request data after merge.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body contains redacted after-fix live output showing authenticated Gmail get and batch-delete requests reaching a loopback-compatible endpoint.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body contains redacted after-fix live output showing authenticated Gmail get and batch-delete requests reaching a loopback-compatible endpoint.

Evidence

Security concerns:

• [medium] Approve the custom credential-bearing endpoint boundary — internal/cmd/root.go:297
  Setting this environment variable routes OAuth bearer credentials and Gmail request data to the selected endpoint; transport validation mitigates plaintext remote use but does not make the remote endpoint trusted.
  Confidence: 0.98

What I checked:

• Current main lacks this capability: Current main constructs the shared factory with only Photos endpoint overrides and its Gmail factory methods always use the default Gmail service endpoint. (internal/cmd/root.go:297, eb85a99366eb)
• Scoped endpoint validation: The PR accepts only absolute HTTPS URLs or loopback HTTP URLs before adding the value to runtime setup. (internal/cmd/gmail_base_url.go:16, 5699ae24b86d)
• All intended Gmail client paths use the override: The shared factory applies the configured endpoint to both normal Gmail and batch-delete service construction; command runtime wiring uses these factory methods. (internal/googleapi/factory.go:125, 5699ae24b86d)
• Credential-routing boundary is documented: The environment-variable reference states that the selected endpoint receives OAuth bearer credentials and Gmail data. (docs/spec.md:179, 5699ae24b86d)
• After-fix live behavior proof: The PR body records successful GET and batch-delete requests against a loopback-compatible endpoint, including bearer-authentication presence without exposing token or mailbox data. (internal/cmd/gmail_base_url_test.go:49, 5699ae24b86d)
• Feature-history routing: History identifies the shared runtime Google-service factory as part of Peter Steinberger's refactor; current history also shows substantial ongoing work in these central Gmail/service paths. (internal/googleapi/factory.go:48, b1af2c653d3a)

Likely related people:

• steipete: History ties the shared runtime Google-service factory to this author, who also dominates the recent history of the affected factory, Gmail, and runtime paths. (role: shared Google-service factory author and recent area contributor; confidence: high; commits: b1af2c653d3a, cd965f1d38bb; files: internal/googleapi/factory.go, internal/googleapi/gmail.go, internal/cmd/root.go)

Rank-up moves

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

• Obtain explicit maintainer approval for the operator-configured credential-routing boundary.

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 (4 earlier review cycles)

• reviewed 2026-08-18T04:33:26.149Z sha 91d4451 :: needs real behavior proof before merge. :: [P2] Document the Gmail credential-routing boundary
• reviewed 2026-08-18T15:29:56.067Z sha a94dd84 :: needs real behavior proof before merge. :: [P1] Restrict custom endpoints to HTTPS or loopback HTTP
• reviewed 2026-08-18T17:41:43.442Z sha a94dd84 :: needs changes before merge. :: [P1] Restrict custom endpoints to HTTPS or loopback HTTP
• reviewed 2026-08-18T18:50:11.797Z sha 5699ae2 :: needs maintainer review before merge. :: none

[sallyom]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event exact_review_queue).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/32175091277
• Updated: 2026-08-18T19:10:30.769Z

[sallyom]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event exact_review_queue).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/32173348066
• Updated: 2026-08-18T18:51:50.567Z

[sallyom]

wrt [P1]:
GOG_GMAIL_BASE_UR is an explicit operator-controlled trust boundary. It intentionally sends OAuth bearer credentials and Gmail request data to that endpoint when configured. The default remains the Google Gmail API; remote overrides require HTTPS, and HTTP is restricted to loopback. This behavior and its security implications are documented.