opencode-gemini-auth-proxy 1.3.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jens
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,254 @@
+# Gemini OAuth Plugin for Opencode
+
+![License](https://img.shields.io/npm/l/opencode-gemini-auth)
+![Version](https://img.shields.io/npm/v/opencode-gemini-auth)
+
+**Authenticate the Opencode CLI with your Google account.** This plugin enables
+you to use your existing Gemini plan and quotas (including the free tier)
+directly within Opencode, bypassing separate API billing.
+
+## Prerequisites
+
+- [Opencode CLI](https://opencode.ai) installed.
+- A Google account with access to Gemini.
+
+## Installation
+
+Add the plugin to your Opencode configuration file
+(`~/.config/opencode/opencode.json` or similar):
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-gemini-auth@latest"]
+}
+```
+
+> [!IMPORTANT]
+> If you're using a paid Gemini Code Assist subscription (Standard/Enterprise),
+> explicitly configure a Google Cloud `projectId`. Free tier accounts should
+> auto-provision a managed project, but you can still set `projectId` to force
+> a specific project.
+
+## Usage
+
+1. **Login**: Run the authentication command in your terminal:
+
+   ```bash
+   opencode auth login
+   ```
+
+2. **Select Provider**: Choose **Google** from the list.
+3. **Authenticate**: Select **OAuth with Google (Gemini CLI)**.
+   - A browser window will open for you to approve the access.
+   - The plugin spins up a temporary local server to capture the callback.
+   - If the local server fails (e.g., port in use or headless environment),
+     you can manually paste the callback URL or just the authorization code.
+
+Once authenticated, Opencode will use your Google account for Gemini requests.
+
+## Configuration
+
+### Google Cloud Project
+
+By default, the plugin attempts to provision or find a suitable Google Cloud
+project. To force a specific project, set the `projectId` in your configuration
+or via environment variables:
+
+**File:** `~/.config/opencode/opencode.json`
+
+```json
+{
+  "provider": {
+    "google": {
+      "options": {
+        "projectId": "your-specific-project-id"
+      }
+    }
+  }
+}
+```
+
+You can also set `OPENCODE_GEMINI_PROJECT_ID`, `GOOGLE_CLOUD_PROJECT`, or
+`GOOGLE_CLOUD_PROJECT_ID` to supply the project ID via environment variables.
+
+### Model list
+
+Below are example model entries you can add under `provider.google.models` in your
+Opencode config. Each model can include an `options.thinkingConfig` block to
+enable "thinking" features.
+
+```json
+{
+  "provider": {
+    "google": {
+      "models": {
+        "gemini-2.5-flash": {
+          "options": {
+            "thinkingConfig": {
+              "thinkingBudget": 8192,
+              "includeThoughts": true
+            }
+          }
+        },
+        "gemini-2.5-pro": {
+          "options": {
+            "thinkingConfig": {
+              "thinkingBudget": 8192,
+              "includeThoughts": true
+            }
+          }
+        },
+        "gemini-3-flash-preview": {
+          "options": {
+            "thinkingConfig": {
+              "thinkingLevel": "high",
+              "includeThoughts": true
+            }
+          }
+        },
+        "gemini-3-pro-preview": {
+          "options": {
+            "thinkingConfig": {
+              "thinkingLevel": "high",
+              "includeThoughts": true
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Note: Available model names and previews may change—check Google's documentation or
+the Gemini product page for the current model identifiers.
+
+### Thinking Models
+
+The plugin supports configuring Gemini "thinking" features per-model via
+`thinkingConfig`. The available fields depend on the model family:
+
+- For Gemini 3 models: use `thinkingLevel` with values `"low"` or `"high"`.
+- For Gemini 2.5 models: use `thinkingBudget` (token count).
+- `includeThoughts` (boolean) controls whether the model emits internal thoughts.
+
+A combined example showing both model types:
+
+```json
+{
+  "provider": {
+    "google": {
+      "models": {
+        "gemini-3-pro-preview": {
+          "options": {
+            "thinkingConfig": {
+              "thinkingLevel": "high",
+              "includeThoughts": true
+            }
+          }
+        },
+        "gemini-2.5-flash": {
+          "options": {
+            "thinkingConfig": {
+              "thinkingBudget": 8192,
+              "includeThoughts": true
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+If you don't set a `thinkingConfig` for a model, the plugin will use default
+behavior for that model.
+
+## Troubleshooting
+
+### Manual Google Cloud Setup
+
+If automatic provisioning fails, you may need to set up the project manually:
+
+1. Go to the [Google Cloud Console](https://console.cloud.google.com/).
+2. Create or select a project.
+3. Enable the **Gemini for Google Cloud API**
+   (`cloudaicompanion.googleapis.com`).
+4. Configure the `projectId` in your Opencode config as shown above.
+
+### Quotas, Plans, and 429 Errors
+
+Common causes of `429 RESOURCE_EXHAUSTED` or `QUOTA_EXHAUSTED`:
+
+- **No project ID configured**: the plugin uses a managed free-tier project, which has lower quotas.
+- **Model-specific limits**: quotas are tracked per model (e.g., `gemini-3-pro-preview` vs `gemini-3-flash-preview`).
+- **Large prompts**: OAuth/Code Assist does not support cached content, so long system prompts and history can burn quota quickly.
+- **Parallel sessions**: multiple Opencode windows can drain the same bucket.
+
+Notes:
+
+- **Gemini CLI auto-fallbacks**: the official CLI may fall back to Flash when Pro quotas are exhausted, so it can appear to “work” even if the Pro bucket is depleted.
+- **Paid plans still require a project**: to use paid quotas in Opencode, set `provider.google.options.projectId` (or `OPENCODE_GEMINI_PROJECT_ID`) and re-authenticate.
+
+### Debugging
+
+To view detailed logs of Gemini requests and responses, set the
+`OPENCODE_GEMINI_DEBUG` environment variable:
+
+```bash
+OPENCODE_GEMINI_DEBUG=1 opencode
+```
+
+This will generate `gemini-debug-<timestamp>.log` files in your working
+directory containing sanitized request/response details.
+
+## Parity Notes
+
+This plugin mirrors the official Gemini CLI OAuth flow and Code Assist
+endpoints. In particular, project onboarding and quota retry handling follow
+the same behavior patterns as the Gemini CLI.
+
+### References
+
+- Gemini CLI repository: https://github.com/google-gemini/gemini-cli
+- Gemini CLI quota documentation: https://developers.google.com/gemini-code-assist/resources/quotas
+
+### Updating
+
+Opencode does not automatically update plugins. To update to the latest version,
+you must clear the cached plugin:
+
+```bash
+# Clear the specific plugin cache
+rm -rf ~/.cache/opencode/node_modules/opencode-gemini-auth
+
+# Run Opencode to trigger a fresh install
+opencode
+```
+
+## Development
+
+To develop on this plugin locally:
+
+1. **Clone**:
+
+   ```bash
+   git clone https://github.com/jenslys/opencode-gemini-auth.git
+   cd opencode-gemini-auth
+   bun install
+   ```
+
+2. **Link**:
+   Update your Opencode config to point to your local directory using a
+   `file://` URL:
+
+   ```json
+   {
+     "plugin": ["file:///absolute/path/to/opencode-gemini-auth"]
+   }
+   ```
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,14 @@
+export {
+  GeminiCLIOAuthPlugin,
+  GoogleOAuthPlugin,
+} from "./src/plugin";
+
+export {
+  authorizeGemini,
+  exchangeGeminiWithVerifier,
+} from "./src/gemini/oauth";
+
+export type {
+  GeminiAuthorization,
+  GeminiTokenExchangeResult,
+} from "./src/gemini/oauth";

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "opencode-gemini-auth-proxy",
+  "module": "index.ts",
+  "version": "1.3.10",
+  "author": "jenslys",
+  "repository": "https://github.com/jenslys/opencode-gemini-auth",
+  "files": [
+    "index.ts",
+    "src"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.1.48",
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@openauthjs/openauth": "^0.4.3"
+  }
+}

package/src/constants.ts

@@ -0,0 +1,39 @@
+/**
+ * Constants used for Google Gemini OAuth flows and Cloud Code Assist API integration.
+ */
+export const GEMINI_CLIENT_ID = "681255809395-oo8ft2oprdrnp9e3aqf6av3hmdib135j.apps.googleusercontent.com";
+
+/**
+ * Client secret issued for the Gemini CLI OAuth application.
+ */
+export const GEMINI_CLIENT_SECRET = "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";
+
+/**
+ * Scopes required for Gemini CLI integrations.
+ */
+export const GEMINI_SCOPES: readonly string[] = [
+  "https://www.googleapis.com/auth/cloud-platform",
+  "https://www.googleapis.com/auth/userinfo.email",
+  "https://www.googleapis.com/auth/userinfo.profile",
+];
+
+/**
+ * OAuth redirect URI used by the local CLI callback server.
+ */
+export const GEMINI_REDIRECT_URI = "http://localhost:8085/oauth2callback";
+
+/**
+ * Root endpoint for the Cloud Code Assist API which backs Gemini CLI traffic.
+ */
+export const GEMINI_CODE_ASSIST_ENDPOINT = "https://cloudcode-pa.googleapis.com";
+
+export const CODE_ASSIST_HEADERS = {
+  "User-Agent": "google-api-nodejs-client/9.15.1",
+  "X-Goog-Api-Client": "gl-node/22.17.0",
+  "Client-Metadata": "ideType=IDE_UNSPECIFIED,platform=PLATFORM_UNSPECIFIED,pluginType=GEMINI",
+} as const;
+
+/**
+ * Provider identifier shared between the plugin loader and credential store.
+ */
+export const GEMINI_PROVIDER_ID = "google";

package/src/fetch.ts

@@ -0,0 +1,11 @@
+export default (
+  input: RequestInfo,
+  init?: RequestInit
+): Promise<Response> =>
+  fetch(input, {
+    // https://bun.com/docs/guides/http/proxy
+    ...(process.env.OPENCODE_GEMINI_AUTH_PROXY
+      ? { proxy: process.env.OPENCODE_GEMINI_AUTH_PROXY }
+      : {}),
+    ...(init ?? {})
+  })

package/src/gemini/oauth.ts

@@ -0,0 +1,178 @@
+import proxyFetch from "../fetch";
+import { generatePKCE } from "@openauthjs/openauth/pkce";
+import { randomBytes } from "node:crypto";
+
+import {
+  GEMINI_CLIENT_ID,
+  GEMINI_CLIENT_SECRET,
+  GEMINI_REDIRECT_URI,
+  GEMINI_SCOPES,
+} from "../constants";
+import {
+  formatDebugBodyPreview,
+  isGeminiDebugEnabled,
+  logGeminiDebugMessage,
+} from "../plugin/debug";
+
+interface PkcePair {
+  challenge: string;
+  verifier: string;
+}
+
+/**
+ * Result returned to the caller after constructing an OAuth authorization URL.
+ */
+export interface GeminiAuthorization {
+  url: string;
+  verifier: string;
+  state: string;
+}
+
+interface GeminiTokenExchangeSuccess {
+  type: "success";
+  refresh: string;
+  access: string;
+  expires: number;
+  email?: string;
+}
+
+interface GeminiTokenExchangeFailure {
+  type: "failed";
+  error: string;
+}
+
+export type GeminiTokenExchangeResult =
+  | GeminiTokenExchangeSuccess
+  | GeminiTokenExchangeFailure;
+
+interface GeminiTokenResponse {
+  access_token: string;
+  expires_in: number;
+  refresh_token: string;
+}
+
+interface GeminiUserInfo {
+  email?: string;
+}
+
+/**
+ * Build the Gemini OAuth authorization URL including PKCE.
+ */
+export async function authorizeGemini(): Promise<GeminiAuthorization> {
+  const pkce = (await generatePKCE()) as PkcePair;
+  const state = randomBytes(32).toString("hex");
+
+  const url = new URL("https://accounts.google.com/o/oauth2/v2/auth");
+  url.searchParams.set("client_id", GEMINI_CLIENT_ID);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("redirect_uri", GEMINI_REDIRECT_URI);
+  url.searchParams.set("scope", GEMINI_SCOPES.join(" "));
+  url.searchParams.set("code_challenge", pkce.challenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  url.searchParams.set("state", state);
+  url.searchParams.set("access_type", "offline");
+  url.searchParams.set("prompt", "consent");
+  // Add a fragment so any stray terminal glyphs are ignored by the auth server.
+  url.hash = "opencode";
+
+  return {
+    url: url.toString(),
+    verifier: pkce.verifier,
+    state,
+  };
+}
+
+/**
+ * Exchange an authorization code using a known PKCE verifier.
+ */
+export async function exchangeGeminiWithVerifier(
+  code: string,
+  verifier: string,
+): Promise<GeminiTokenExchangeResult> {
+  try {
+    return await exchangeGeminiWithVerifierInternal(code, verifier);
+  } catch (error) {
+    return {
+      type: "failed",
+      error: error instanceof Error ? error.message : "Unknown error",
+    };
+  }
+}
+
+async function exchangeGeminiWithVerifierInternal(
+  code: string,
+  verifier: string,
+): Promise<GeminiTokenExchangeResult> {
+  if (isGeminiDebugEnabled()) {
+    logGeminiDebugMessage("OAuth exchange: POST https://oauth2.googleapis.com/token");
+  }
+  const tokenResponse = await proxyFetch("https://oauth2.googleapis.com/token", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/x-www-form-urlencoded",
+    },
+    body: new URLSearchParams({
+      client_id: GEMINI_CLIENT_ID,
+      client_secret: GEMINI_CLIENT_SECRET,
+      code,
+      grant_type: "authorization_code",
+      redirect_uri: GEMINI_REDIRECT_URI,
+      code_verifier: verifier,
+    }),
+  });
+
+  if (!tokenResponse.ok) {
+    const errorText = await tokenResponse.text();
+    if (isGeminiDebugEnabled()) {
+      logGeminiDebugMessage(
+        `OAuth exchange response: ${tokenResponse.status} ${tokenResponse.statusText}`,
+      );
+      const preview = formatDebugBodyPreview(errorText);
+      if (preview) {
+        logGeminiDebugMessage(`OAuth exchange error body: ${preview}`);
+      }
+    }
+    return { type: "failed", error: errorText };
+  }
+
+  const tokenPayload = (await tokenResponse.json()) as GeminiTokenResponse;
+  if (isGeminiDebugEnabled()) {
+    logGeminiDebugMessage(
+      `OAuth exchange success: expires_in=${tokenPayload.expires_in}s refresh_token=${tokenPayload.refresh_token ? "yes" : "no"}`,
+    );
+  }
+
+  if (isGeminiDebugEnabled()) {
+    logGeminiDebugMessage("OAuth userinfo: GET https://www.googleapis.com/oauth2/v1/userinfo");
+  }
+  const userInfoResponse = await proxyFetch(
+    "https://www.googleapis.com/oauth2/v1/userinfo?alt=json",
+    {
+      headers: {
+        Authorization: `Bearer ${tokenPayload.access_token}`,
+      },
+    },
+  );
+  if (isGeminiDebugEnabled()) {
+    logGeminiDebugMessage(
+      `OAuth userinfo response: ${userInfoResponse.status} ${userInfoResponse.statusText}`,
+    );
+  }
+
+  const userInfo = userInfoResponse.ok
+    ? ((await userInfoResponse.json()) as GeminiUserInfo)
+    : {};
+
+  const refreshToken = tokenPayload.refresh_token;
+  if (!refreshToken) {
+    return { type: "failed", error: "Missing refresh token in response" };
+  }
+
+  return {
+    type: "success",
+    refresh: refreshToken,
+    access: tokenPayload.access_token,
+    expires: Date.now() + tokenPayload.expires_in * 1000,
+    email: userInfo.email,
+  };
+}

package/src/plugin/auth.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "bun:test";
+
+import {
+  accessTokenExpired,
+  formatRefreshParts,
+  isOAuthAuth,
+  parseRefreshParts,
+} from "./auth";
+
+describe("auth helpers", () => {
+  it("parses refresh parts with project and managed ids", () => {
+    const parts = parseRefreshParts("refresh|project-123|managed-456");
+    expect(parts.refreshToken).toBe("refresh");
+    expect(parts.projectId).toBe("project-123");
+    expect(parts.managedProjectId).toBe("managed-456");
+  });
+
+  it("formats refresh parts with optional segments", () => {
+    expect(formatRefreshParts({ refreshToken: "refresh" })).toBe("refresh");
+    expect(
+      formatRefreshParts({
+        refreshToken: "refresh",
+        projectId: "project-123",
+      }),
+    ).toBe("refresh|project-123|");
+    expect(
+      formatRefreshParts({
+        refreshToken: "refresh",
+        managedProjectId: "managed-456",
+      }),
+    ).toBe("refresh||managed-456");
+  });
+
+  it("detects OAuth auth payloads", () => {
+    expect(isOAuthAuth({ type: "oauth", refresh: "refresh" })).toBe(true);
+    expect(isOAuthAuth({ type: "api", refresh: "refresh" } as never)).toBe(false);
+  });
+
+  it("treats tokens near expiry as expired", () => {
+    const now = Date.now();
+    expect(
+      accessTokenExpired({
+        type: "oauth",
+        refresh: "refresh",
+        access: "access",
+        expires: now + 59_000,
+      }),
+    ).toBe(true);
+    expect(
+      accessTokenExpired({
+        type: "oauth",
+        refresh: "refresh",
+        access: "access",
+        expires: now + 61_000,
+      }),
+    ).toBe(false);
+  });
+});

package/src/plugin/auth.ts

@@ -0,0 +1,46 @@
+import type { AuthDetails, OAuthAuthDetails, RefreshParts } from "./types";
+
+const ACCESS_TOKEN_EXPIRY_BUFFER_MS = 60 * 1000;
+
+export function isOAuthAuth(auth: AuthDetails): auth is OAuthAuthDetails {
+  return auth.type === "oauth";
+}
+
+/**
+ * Splits a packed refresh string into its constituent refresh token and project IDs.
+ */
+export function parseRefreshParts(refresh: string): RefreshParts {
+  const [refreshToken = "", projectId = "", managedProjectId = ""] = (refresh ?? "").split("|");
+  return {
+    refreshToken,
+    projectId: projectId || undefined,
+    managedProjectId: managedProjectId || undefined,
+  };
+}
+
+/**
+ * Serializes refresh token parts into the stored string format.
+ */
+export function formatRefreshParts(parts: RefreshParts): string {
+  if (!parts.refreshToken) {
+    return "";
+  }
+
+  if (!parts.projectId && !parts.managedProjectId) {
+    return parts.refreshToken;
+  }
+
+  const projectSegment = parts.projectId ?? "";
+  const managedSegment = parts.managedProjectId ?? "";
+  return `${parts.refreshToken}|${projectSegment}|${managedSegment}`;
+}
+
+/**
+ * Determines whether an access token is expired or missing, with buffer for clock skew.
+ */
+export function accessTokenExpired(auth: OAuthAuthDetails): boolean {
+  if (!auth.access || typeof auth.expires !== "number") {
+    return true;
+  }
+  return auth.expires <= Date.now() + ACCESS_TOKEN_EXPIRY_BUFFER_MS;
+}