feat(auth): customize the OAuth callback for remote-host logins

[npeshkov]

Description

gws auth login's flow assumes the browser can reach the CLI's callback server on localhost.

When the CLI runs on a remote host (e.g. a cloud development environment), the server is not reachable from the developer's laptop browser, so the OAuth callback has to be redirected to an address other than the laptop's localhost.

This Pull Request adds three optional environment variables that let the caller customize the OAuth flow:

• GOOGLE_WORKSPACE_CLI_OAUTH_REDIRECT_URI - sets the redirect URI sent to Google.
• GOOGLE_WORKSPACE_CLI_OAUTH_STATE - a state value passed to the authorization URL (see use cases).
• GOOGLE_WORKSPACE_CLI_OAUTH_PORT - sets the port of the local callback listener.

Implementation notes

• The authorisation code could be percent-encoded on the way between Google's server and the remote host. This will lead to invalid_grant: Malformed auth code, unless the code is decoded by gws.
• When GOOGLE_WORKSPACE_CLI_OAUTH_STATE is set, the state returned on the callback is verified against it. A missing or mismatched value is rejected to guard against forged (CSRF) callbacks.
• The callback server bounds how much it reads from the request line (8 KiB), so a client that never sends a newline cannot exhaust memory (DoS) - relevant now that the port may be reachable from remote networks.
• Moved helper for testing with environment variables from auth.rs to test_support.rs.

Checklist

• My code follows the AGENTS.md guidelines (no generated google-* crates).
• I have run cargo fmt --all to format the code perfectly.
• I have run cargo clippy -- -D warnings and resolved all warnings.
• I have added tests that prove my fix is effective or that my feature works.
• I have provided a Changeset file (e.g. via pnpx changeset) to document my changes.

[changeset-bot]

🦋 Changeset detected

Latest commit: d1cf429

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@googleworkspace/cli	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[googleworkspace-bot]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces support for customizing the OAuth callback flow in gws auth login via new environment variables (GOOGLE_WORKSPACE_CLI_OAUTH_REDIRECT_URI, GOOGLE_WORKSPACE_CLI_OAUTH_STATE, and GOOGLE_WORKSPACE_CLI_OAUTH_PORT) to support remote-host logins. It also refactors EnvVarGuard into a shared test helper module. The review feedback highlights a security vulnerability where the received state parameter is not validated against the configured GOOGLE_WORKSPACE_CLI_OAUTH_STATE environment variable, exposing the flow to CSRF attacks. It is recommended to update extract_authorization_code to validate the state and add corresponding unit tests.

[googleworkspace-bot]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces customization options for the gws auth login OAuth callback to support remote-host logins via three new environment variables: GOOGLE_WORKSPACE_CLI_OAUTH_REDIRECT_URI, GOOGLE_WORKSPACE_CLI_OAUTH_STATE, and GOOGLE_WORKSPACE_CLI_OAUTH_PORT. It also refactors the EnvVarGuard test helper into a shared module and adds corresponding unit tests and documentation. Feedback highlights two main issues: first, a potential routing failure if a custom redirect URI is used without pinning the local port (which defaults to a random port); second, a security vulnerability where reading the HTTP request line without a byte limit could lead to a Denial of Service (DoS) via memory exhaustion.

[googleworkspace-bot]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces customization options for the OAuth callback in gws auth login to support remote-host logins. It adds three new environment variables (GOOGLE_WORKSPACE_CLI_OAUTH_REDIRECT_URI, GOOGLE_WORKSPACE_CLI_OAUTH_STATE, and GOOGLE_WORKSPACE_CLI_OAUTH_PORT) along with state verification to prevent CSRF. Additionally, it refactors the EnvVarGuard helper into a shared test module and adds comprehensive unit tests. Feedback suggests printing the local port or warning the user when a custom redirect URI is used without pinning the port, as they otherwise cannot easily determine which port to forward.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enables the gws auth login command to function in remote development environments (like cloud-based IDEs) where the browser cannot directly access the CLI's local callback server. By allowing users to override the redirect URI, pin the callback port, and provide a state parameter for CSRF validation, the authentication flow becomes more flexible and secure for non-local setups.

Highlights

• OAuth Callback Customization: Introduced three environment variables (GOOGLE_WORKSPACE_CLI_OAUTH_REDIRECT_URI, GOOGLE_WORKSPACE_CLI_OAUTH_STATE, and GOOGLE_WORKSPACE_CLI_OAUTH_PORT) to support OAuth flows on remote hosts where the default localhost callback is unreachable.
• Security Enhancements: Added CSRF protection by verifying the state parameter in the OAuth callback and implemented a request size limit on the callback server to prevent potential DoS attacks.
• Refactoring: Moved the EnvVarGuard test helper to a new test_support.rs module to improve code reuse across the test suite.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Generative AI Prohibited Use Policy, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces customization options for the OAuth login callback in the CLI, facilitating remote-host login scenarios. It adds three new environment variables (GOOGLE_WORKSPACE_CLI_OAUTH_REDIRECT_URI, GOOGLE_WORKSPACE_CLI_OAUTH_STATE, and GOOGLE_WORKSPACE_CLI_OAUTH_PORT) to override the redirect URI, set and verify the OAuth state (protecting against CSRF), and pin the local callback port. Additionally, the EnvVarGuard test helper has been refactored into a shared test_support module, and documentation has been updated accordingly. There are no review comments, so I have no feedback to provide.