feat(mcp): OAuth2 PKCE Authorization Server for HTTP transport

[shigechika]

Summary

• Implements MCP Authorization spec 2025-11-25 on the Streamable HTTP transport
• Enable with gws mcp --transport http --auth; Phase 1 (no --auth) is unchanged
• New OAuth2 AS endpoints: RFC 9728 protected-resource metadata, RFC 8414 AS metadata, DCR stub, PKCE S256 authorize/callback/token flow via Google OAuth2
• Bearer auth axum middleware: all /mcp requests require Authorization: Bearer <token>; unauthenticated requests get 401 with WWW-Authenticate pointing to AS metadata
• Session TTL 8 h; pending auth TTL 10 min (in-memory)
• RFC 7636 §4.6 PKCE S256 unit tests added
• FORK.md updated with --auth usage, prerequisites, and endpoint table

Endpoints added

Endpoint	RFC
/.well-known/oauth-protected-resource	RFC 9728
/.well-known/oauth-authorization-server	RFC 8414
/oauth/register	RFC 7591 stub
/oauth/authorize	RFC 6749
/oauth/callback	—
/oauth/token	RFC 6749 + RFC 7636 PKCE S256

Prerequisites for --auth

1. gws auth setup — creates client_secret.json with a Google OAuth2 web app credential
2. Add http://localhost:<port>/oauth/callback as an Authorized redirect URI in Google Cloud Console

Test plan

• cargo clippy -- -D warnings — clean
• cargo test — 826 passed
• PKCE S256 unit tests (RFC 7636 §4.6 worked example + wrong-verifier rejection)
• Smoke test: Phase 1 (--transport http no --auth) — /mcp returns 406 (correct), /.well-known/oauth-protected-resource returns 404 (correct, routes not registered)
• Smoke test: --auth without client_secret.json exits with clear error message

Note (Phase 2/3): GWS API calls still use the shared gws auth login token. Bearer tokens identify the user by email but do not yet carry per-user GWS credentials. Per-user token isolation is Phase 4.

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: b37314b

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

[shigechika]

Opened by mistake — this belongs in the fork. Closing immediately.

[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 significantly enhances the MCP server capabilities by introducing a secure HTTP transport layer with OAuth2 PKCE authentication. It also expands the utility of the MCP server through new helper tools that simplify common Gmail operations, while resolving several upstream-reported bugs related to authentication, scope management, and API data parsing.

Highlights

• MCP Authorization Server: Implemented an OAuth2 PKCE Authorization Server for the HTTP transport, supporting RFC 9728 and RFC 8414 metadata, and PKCE S256 flows.
• HTTP Transport Auth: Added bearer token authentication for all /mcp requests when using the HTTP transport, with session management and 401 challenge responses.
• Helper Tools: Introduced convenience helper tools like gmail_send and gmail_reply to automate complex API interactions like RFC 2822 formatting.
• Bug Fixes & Improvements: Addressed multiple issues including Gmail display-name lookup, unpadded base64url decoding, and TUI scope-picker policy conflicts.

Ignored Files

• Ignored by pattern: .github/workflows/** (12)
  • .github/workflows/auto-tag.yml
  • .github/workflows/automation.yml
  • .github/workflows/ci.yml
  • .github/workflows/cla.yml
  • .github/workflows/coverage.yml
  • .github/workflows/generate-skills.yml
  • .github/workflows/publish-skills.yml
  • .github/workflows/release-changesets.yml
  • .github/workflows/release-fork.yml
  • .github/workflows/release.yml
  • .github/workflows/stale.yml
  • .github/workflows/sync-upstream.yml

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. ↩

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[gemini-code-assist]

Code Review

This pull request adds Model Context Protocol (MCP) server support to the Google Workspace CLI, implementing both stdio and HTTP transports along with an OAuth2 PKCE authorization server. It introduces AI-friendly helper tools for Gmail and resolves several upstream issues regarding scope mapping and base64 decoding. The review feedback highlights critical security and stability concerns, specifically an open redirect vulnerability in the authorization endpoint, a potential memory leak from unpruned sessions, and the need to sanitize terminal output to prevent escape sequence injection.

[gemini-code-assist]

The oauth_authorize endpoint does not validate the redirect_uri parameter against an allowlist or registered client metadata. This creates an Open Redirect vulnerability where an attacker can trick a user into logging in and then redirect them to a malicious site, potentially stealing the authorization code. Per the MCP Authorization spec (2025-11-25), the authorization server MUST validate the redirection URI. For a local MCP server, you should at least restrict redirects to loopback addresses.

async fn oauth_authorize(
    State(state): State<AppState>,
    Query(p): Query<AuthorizeParams>,
) -> Result<Redirect, (StatusCode, String)> {
    // Validate redirect_uri to prevent Open Redirect vulnerabilities.
    // For a local MCP server, we restrict redirects to loopback addresses.
    if !p.redirect_uri.starts_with("http://localhost") 
        && !p.redirect_uri.starts_with("http://127.0.0.1") 
    {
        return Err((
            StatusCode::BAD_REQUEST,
            "invalid_redirect_uri: only loopback addresses are allowed".to_string(),
        ));
    }

[gemini-code-assist]

The sessions map in AuthStore is never pruned, leading to a memory leak as new sessions are created over time. While bearer_auth_middleware checks for expiration, it does not remove expired entries. You should remove the session from the map if it is found to be expired to prevent memory exhaustion.

    let mut sessions = state.auth_store.sessions.lock().await;
    let is_valid = match sessions.get(&token) {
        Some(s) => !is_expired(s.created_at, SESSION_TTL),
        None => false,
    };
    if !is_valid {
        sessions.remove(&token);
        return (
            StatusCode::UNAUTHORIZED,
            [(
                "WWW-Authenticate",
                "Bearer realm=\"gws-mcp\", error=\"invalid_token\", resource_metadata=\"/.well-known/oauth-protected-resource\"",
            )],
        )
            .into_response();
    }

References

1. Avoid introducing changes that are outside the primary goal of a pull request to prevent scope creep.

[gemini-code-assist]

The error message e is printed directly to the terminal without sanitization. Since GwsError can contain strings returned from external Google APIs, this could allow for escape sequence injection. Please use crate::output::sanitize_for_terminal before printing.

            eprintln!(
                "[gws mcp] Warning: Authentication failed, proceeding without credentials: {}",
                crate::output::sanitize_for_terminal(&e.to_string())
            );

[gemini-code-assist]

The tool name and error message are printed to the terminal without sanitization. Since these can contain data from external Discovery documents, they should be sanitized to prevent escape sequence injection.

                            eprintln!(
                                "[gws mcp] Warning: skipping tool '{}': {}",
                                crate::output::sanitize_for_terminal(name),
                                crate::output::sanitize_for_terminal(&e.to_string())
                            );