fix(core): dynamically resolve Cloud Workstations proxy redirect URI for OAuth flows

[amelidev]

Summary

This PR resolves an issue where OAuth 2.0 authentication flows inside Google
Cloud Workstations VMs fail because they are statically configured to redirect
back to localhost (e.g., http://localhost:\${redirectPort}/oauth/callback).

Since the developer's web browser runs locally on their physical laptop, the
browser cannot navigate the localhost loopback back to the remote VM context,
leading to connection refusal.

This fix dynamically detects the Google Cloud Workstations environment context
(via GOOGLE_CLOUD_WORKSTATIONS and WEB_HOST environment variables) and
constructs the correct authenticated reverse proxy callback URL format
(https://\${redirectPort}-\${process.env['WEB_HOST']}/oauth/callback), routing
the authentication response securely back to the workstation VM.

Details

• Centralized Workstation Helper: Added getRedirectUri in
  packages/core/src/utils/oauth-flow.ts to encapsulate the environment
  detection and dynamic URL resolution logic.
• Selective Application:
  • Applied the helper to MCP OAuth flows
    (packages/core/src/mcp/oauth-provider.ts and
    packages/core/src/utils/oauth-flow.ts) where third-party IDPs (such as
    Auth0 configured by customers like CME Group) are used.
  • Google Code Assist flow (packages/core/src/code_assist/oauth2.ts) was
    intentionally left unchanged. Google's official "Desktop App" client ID
    strictly prohibits non-loopback redirect URIs and throws
    redirect_uri_mismatch if dynamic proxy domains are supplied. The Code
    Assist flow continues to safely utilize the manual code copy-paste
    out-of-band (authWithUserCode) flow in headless or remote VM environments.
• Clean Imports & Warnings: Removed unused imports (like REDIRECT_PATH in
  oauth-provider.ts) to avoid compilation issues.

Related Issues

Fixes #23711

How to Validate

Automated Unit Tests

Run the newly added unit tests that simulate and verify the Google Cloud
Workstations proxy callback resolution:

npm test -w @google/gemini-cli-core -- src/utils/oauth-flow.test.ts --run
npm test -w @google/gemini-cli-core -- src/mcp/oauth-provider.test.ts --run

Manual Verification

1. Run Gemini CLI inside a terminal/workspace on a remote Cloud Workstation VM.
2. Configure an MCP server that uses OAuth (e.g., Fast MCP Auth0 integration).
3. Trigger an action requiring MCP server access.
4. The CLI starts a local HTTP callback server (e.g., on port 8090).
5. Copy the printed authorization URL (constructed with
   https://8090-<WEB_HOST>/oauth/callback) to your laptop browser.
6. Authenticate successfully. The browser will redirect through the Cloud
   Workstation Gateway proxy, routing the request down to the workstation VM to
   complete the login seamlessly.

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any)
• Validated on required platforms/methods:
  • MacOS
    • npm run
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows
    • npm run
    • npx
    • Docker
  • Linux
    • npm run
    • npx
    • Docker

[github-actions]

📊 PR Size: size/L

• Lines changed: 667
• Additions: +558
• Deletions: -109
• Files changed: 6

[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 addresses authentication failures encountered when running OAuth 2.0 flows within Google Cloud Workstations. By replacing static 'localhost' redirect URIs with a dynamically resolved URL that accounts for the workstation's proxy gateway, the changes enable seamless authentication for remote development environments. The solution is applied selectively to ensure that sensitive flows, such as Google Code Assist, remain unaffected by these changes.

Highlights

• Dynamic Redirect URI Resolution: Introduced a helper function getRedirectUri to dynamically detect Google Cloud Workstations environments and construct the appropriate authenticated reverse proxy callback URL.
• OAuth Flow Integration: Updated MCP OAuth flows to utilize the new dynamic redirect URI, ensuring compatibility with remote workstation environments while maintaining the existing loopback behavior for other contexts.
• Testing and Validation: Added comprehensive unit tests to verify the redirect URI generation logic under simulated Cloud Workstation environment variables.

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 Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, 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 adds support for Google Cloud Workstations by dynamically resolving the OAuth redirect URI to the workstation's proxy URL when running in a workstation environment. It introduces a helper function getRedirectUri and updates the OAuth provider and flow utilities to use it, accompanied by corresponding unit tests. The reviewer pointed out a critical edge case where an explicitly configured localhost or 127.0.0.1 redirect URI would bypass the workstation proxy resolution, leading to connection failures in the browser, and provided a robust code suggestion to handle this scenario.

[amelidev]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a helper function getRedirectUri to handle OAuth redirect URIs when running inside Google Cloud Workstations, mapping local addresses to the Cloud Workstations proxy URL, and adds corresponding unit tests. The review feedback suggests improving getRedirectUri by mutating the URL object directly to preserve query parameters, hashes, and other URL components, as well as adding support for IPv6 loopback addresses.

[amelidev]

/gemini review

[gemini-code-assist]

Code Review

This pull request adds support for Google Cloud Workstations proxy redirect URIs during OAuth flows by introducing a getRedirectUri helper in packages/core/src/utils/oauth-flow.ts and updating MCPOAuthProvider and the OAuth utilities to use it. It also adds comprehensive tests and reformats some skill documentation files. The review feedback correctly identifies a critical issue where prioritizing the configured port over the active redirectPort in getRedirectUri can cause the workstation proxy to forward callbacks to an inactive port. The reviewer suggests always using the active redirectPort and updating the corresponding unit tests to expect this port.

[amelidev]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces support for Google Cloud Workstations proxy redirect URIs during the OAuth flow. It adds a getRedirectUri helper function in oauth-flow.ts that automatically detects if the application is running inside Google Cloud Workstations and rewrites local loopback redirect URIs (localhost, 127.0.0.1, [::1]) to use the workstation's proxy URL format. The MCPOAuthProvider and OAuth flow utilities are updated to use this helper. Extensive unit tests are added to verify the URI conversion logic, and vi.unstubAllEnvs() is integrated into the test cleanup to prevent environment variable leakage. Additionally, minor formatting updates are applied to some built-in skill markdown files. I have no feedback to provide as there are no review comments.

[amelidev]

@DavidAPierce This one is ready to review/merge, all comments and feedback has been addressed

[wissamblue69-dotcom]

Summary

This PR resolves an issue where OAuth 2.0 authentication flows inside Google
Cloud Workstations VMs fail because they are statically configured to redirect
back to localhost (e.g., http://localhost:\${redirectPort}/oauth/callback).

Since the developer's web browser runs locally on their physical laptop, the
browser cannot navigate the localhost loopback back to the remote VM context,
leading to connection refusal.

This fix dynamically detects the Google Cloud Workstations environment context
(via GOOGLE_CLOUD_WORKSTATIONS and WEB_HOST environment variables) and
constructs the correct authenticated reverse proxy callback URL format
(https://\${redirectPort}-\${process.env['WEB_HOST']}/oauth/callback), routing
the authentication response securely back to the workstation VM.

Details

• Centralized Workstation Helper: Added getRedirectUri in
  packages/core/src/utils/oauth-flow.ts to encapsulate the environment
  detection and dynamic URL resolution logic.
• Selective Application:
  • Applied the helper to MCP OAuth flows
    (packages/core/src/mcp/oauth-provider.ts and
    packages/core/src/utils/oauth-flow.ts) where third-party IDPs (such as
    Auth0 configured by customers like CME Group) are used.
  • Google Code Assist flow (packages/core/src/code_assist/oauth2.ts) was
    intentionally left unchanged. Google's official "Desktop App" client ID
    strictly prohibits non-loopback redirect URIs and throws
    redirect_uri_mismatch if dynamic proxy domains are supplied. The Code
    Assist flow continues to safely utilize the manual code copy-paste
    out-of-band (authWithUserCode) flow in headless or remote VM environments.
• Clean Imports & Warnings: Removed unused imports (like REDIRECT_PATH in
  oauth-provider.ts) to avoid compilation issues.

Related Issues

Fixes #23711

How to Validate

Automated Unit Tests

Run the newly added unit tests that simulate and verify the Google Cloud
Workstations proxy callback resolution:

npm test -w @google/gemini-cli-core -- src/utils/oauth-flow.test.ts --run
npm test -w @google/gemini-cli-core -- src/mcp/oauth-provider.test.ts --run

Manual Verification

1. Run Gemini CLI inside a terminal/workspace on a remote Cloud Workstation VM.
2. Configure an MCP server that uses OAuth (e.g., Fast MCP Auth0 integration).
3. Trigger an action requiring MCP server access.
4. The CLI starts a local HTTP callback server (e.g., on port 8090).
5. Copy the printed authorization URL (constructed with
   https://8090-<WEB_HOST>/oauth/callback) to your laptop browser.
6. Authenticate successfully. The browser will redirect through the Cloud
   Workstation Gateway proxy, routing the request down to the workstation VM to
   complete the login seamlessly.

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any)
• Validated on required platforms/methods:
  • MacOS
    • npm run
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows
    • npm run
    • npx
    • Docker
  • Linux
    • npm run
    • npx
    • Docker