opencode-gemini-auth 1.3.9 → 1.3.11

package/README.md

@@ -177,6 +177,20 @@ If automatic provisioning fails, you may need to set up the project manually:
    (`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
@@ -189,6 +203,35 @@ 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
+
+### Local upstream mirror (optional)
+
+For local parity checks, you can keep a separate clone of the official
+`gemini-cli` in this repo at `.local/gemini-cli`.
+
+This mirror is intentionally untracked, so contributors must set it up once on
+their machine:
+
+```bash
+git clone https://github.com/google-gemini/gemini-cli.git .local/gemini-cli
+```
+
+After setup, pull upstream updates with:
+
+```bash
+bun run update:gemini-cli
+```
+
 ### Updating
 
 Opencode does not automatically update plugins. To update to the latest version,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opencode-gemini-auth",
   "module": "index.ts",
-  "version": "1.3.9",
+  "version": "1.3.11",
   "author": "jenslys",
   "repository": "https://github.com/jenslys/opencode-gemini-auth",
   "files": [
@@ -10,6 +10,9 @@
   ],
   "license": "MIT",
   "type": "module",
+  "scripts": {
+    "update:gemini-cli": "git -C .local/gemini-cli pull --ff-only"
+  },
   "devDependencies": {
     "@opencode-ai/plugin": "^1.1.48",
     "@types/bun": "latest"

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/oauth-authorize.ts

@@ -0,0 +1,198 @@
+import { spawn } from "node:child_process";
+
+import { authorizeGemini, exchangeGeminiWithVerifier } from "../gemini/oauth";
+import type { GeminiTokenExchangeResult } from "../gemini/oauth";
+import { isGeminiDebugEnabled, logGeminiDebugMessage } from "./debug";
+import { resolveProjectContextFromAccessToken } from "./project";
+import { startOAuthListener, type OAuthListener } from "./server";
+import type { OAuthAuthDetails } from "./types";
+
+/**
+ * Builds the OAuth authorize callback used by plugin auth methods.
+ */
+export function createOAuthAuthorizeMethod(): () => Promise<{
+  url: string;
+  instructions: string;
+  method: string;
+  callback: (() => Promise<GeminiTokenExchangeResult>) | ((callbackUrl: string) => Promise<GeminiTokenExchangeResult>);
+}> {
+  return async () => {
+    const maybeHydrateProjectId = async (
+      result: GeminiTokenExchangeResult,
+    ): Promise<GeminiTokenExchangeResult> => {
+      if (result.type !== "success" || !result.access) {
+        return result;
+      }
+
+      const projectFromEnv = process.env.OPENCODE_GEMINI_PROJECT_ID?.trim() ?? "";
+      const googleProjectFromEnv =
+        process.env.GOOGLE_CLOUD_PROJECT?.trim() ??
+        process.env.GOOGLE_CLOUD_PROJECT_ID?.trim() ??
+        "";
+      const configuredProjectId = projectFromEnv || googleProjectFromEnv || undefined;
+
+      try {
+        const authSnapshot = {
+          type: "oauth",
+          refresh: result.refresh,
+          access: result.access,
+          expires: result.expires,
+        } satisfies OAuthAuthDetails;
+        const projectContext = await resolveProjectContextFromAccessToken(
+          authSnapshot,
+          result.access,
+          configuredProjectId,
+        );
+
+        if (projectContext.auth.refresh !== result.refresh && isGeminiDebugEnabled()) {
+          logGeminiDebugMessage(
+            `OAuth project resolved during auth: ${projectContext.effectiveProjectId || "none"}`,
+          );
+        }
+        return projectContext.auth.refresh !== result.refresh
+          ? { ...result, refresh: projectContext.auth.refresh }
+          : result;
+      } catch (error) {
+        if (isGeminiDebugEnabled()) {
+          const message = error instanceof Error ? error.message : String(error);
+          console.warn(`[Gemini OAuth] Project resolution skipped: ${message}`);
+        }
+        return result;
+      }
+    };
+
+    const isHeadless = !!(
+      process.env.SSH_CONNECTION ||
+      process.env.SSH_CLIENT ||
+      process.env.SSH_TTY ||
+      process.env.OPENCODE_HEADLESS
+    );
+
+    let listener: OAuthListener | null = null;
+    if (!isHeadless) {
+      try {
+        listener = await startOAuthListener();
+      } catch (error) {
+        const detail = error instanceof Error ? ` (${error.message})` : "";
+        console.log(
+          `Warning: Couldn't start the local callback listener${detail}. You'll need to paste the callback URL or authorization code.`,
+        );
+      }
+    } else {
+      console.log(
+        "Headless environment detected. You'll need to paste the callback URL or authorization code.",
+      );
+    }
+
+    const authorization = await authorizeGemini();
+    if (!isHeadless) {
+      openBrowserUrl(authorization.url);
+    }
+
+    if (listener) {
+      return {
+        url: authorization.url,
+        instructions:
+          "Complete the sign-in flow in your browser. We'll automatically detect the redirect back to localhost.",
+        method: "auto",
+        callback: async (): Promise<GeminiTokenExchangeResult> => {
+          try {
+            const callbackUrl = await listener.waitForCallback();
+            const code = callbackUrl.searchParams.get("code");
+            const state = callbackUrl.searchParams.get("state");
+
+            if (!code || !state) {
+              return { type: "failed", error: "Missing code or state in callback URL" };
+            }
+            if (state !== authorization.state) {
+              return { type: "failed", error: "State mismatch in callback URL (possible CSRF attempt)" };
+            }
+            return await maybeHydrateProjectId(
+              await exchangeGeminiWithVerifier(code, authorization.verifier),
+            );
+          } catch (error) {
+            return {
+              type: "failed",
+              error: error instanceof Error ? error.message : "Unknown error",
+            };
+          } finally {
+            try {
+              await listener?.close();
+            } catch {}
+          }
+        },
+      };
+    }
+
+    return {
+      url: authorization.url,
+      instructions:
+        "Complete OAuth in your browser, then paste the full redirected URL (e.g., http://localhost:8085/oauth2callback?code=...&state=...) or just the authorization code.",
+      method: "code",
+      callback: async (callbackUrl: string): Promise<GeminiTokenExchangeResult> => {
+        try {
+          const { code, state } = parseOAuthCallbackInput(callbackUrl);
+          if (!code) {
+            return { type: "failed", error: "Missing authorization code in callback input" };
+          }
+          if (state && state !== authorization.state) {
+            return { type: "failed", error: "State mismatch in callback input (possible CSRF attempt)" };
+          }
+          return await maybeHydrateProjectId(
+            await exchangeGeminiWithVerifier(code, authorization.verifier),
+          );
+        } catch (error) {
+          return {
+            type: "failed",
+            error: error instanceof Error ? error.message : "Unknown error",
+          };
+        }
+      },
+    };
+  };
+}
+
+function parseOAuthCallbackInput(input: string): { code?: string; state?: string } {
+  const trimmed = input.trim();
+  if (!trimmed) {
+    return {};
+  }
+
+  if (/^https?:\/\//i.test(trimmed)) {
+    try {
+      const url = new URL(trimmed);
+      return {
+        code: url.searchParams.get("code") || undefined,
+        state: url.searchParams.get("state") || undefined,
+      };
+    } catch {
+      return {};
+    }
+  }
+
+  const candidate = trimmed.startsWith("?") ? trimmed.slice(1) : trimmed;
+  if (candidate.includes("=")) {
+    const params = new URLSearchParams(candidate);
+    const code = params.get("code") || undefined;
+    const state = params.get("state") || undefined;
+    if (code || state) {
+      return { code, state };
+    }
+  }
+
+  return { code: trimmed };
+}
+
+function openBrowserUrl(url: string): void {
+  try {
+    const platform = process.platform;
+    const command =
+      platform === "darwin" ? "open" : platform === "win32" ? "rundll32" : "xdg-open";
+    const args = platform === "win32" ? ["url.dll,FileProtocolHandler", url] : [url];
+    const child = spawn(command, args, {
+      stdio: "ignore",
+      detached: true,
+    });
+    child.unref?.();
+  } catch {}
+}

package/src/plugin/project/api.ts

@@ -0,0 +1,209 @@
+import { CODE_ASSIST_HEADERS, GEMINI_CODE_ASSIST_ENDPOINT } from "../../constants";
+import { logGeminiDebugResponse, startGeminiDebugRequest } from "../debug";
+import {
+  FREE_TIER_ID,
+  type LoadCodeAssistPayload,
+  type OnboardUserPayload,
+  ProjectIdRequiredError,
+} from "./types";
+import { buildMetadata, isVpcScError, parseJsonSafe, wait } from "./utils";
+
+/**
+ * Loads managed project information for the given access token and optional project.
+ */
+export async function loadManagedProject(
+  accessToken: string,
+  projectId?: string,
+): Promise<LoadCodeAssistPayload | null> {
+  try {
+    const metadata = buildMetadata(projectId);
+    const requestBody: Record<string, unknown> = { metadata };
+    if (projectId) {
+      requestBody.cloudaicompanionProject = projectId;
+    }
+
+    const url = `${GEMINI_CODE_ASSIST_ENDPOINT}/v1internal:loadCodeAssist`;
+    const headers = {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${accessToken}`,
+      ...CODE_ASSIST_HEADERS,
+    };
+    const debugContext = startGeminiDebugRequest({
+      originalUrl: url,
+      resolvedUrl: url,
+      method: "POST",
+      headers,
+      body: JSON.stringify(requestBody),
+      streaming: false,
+      projectId,
+    });
+
+    const response = await fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(requestBody),
+    });
+    const responseBody = await readResponseTextIfNeeded(response, !!debugContext);
+    if (debugContext) {
+      logGeminiDebugResponse(debugContext, response, { body: responseBody });
+    }
+
+    if (!response.ok) {
+      if (responseBody && isVpcScError(parseJsonSafe(responseBody))) {
+        return { currentTier: { id: "standard-tier" } };
+      }
+      return null;
+    }
+
+    if (responseBody) {
+      return parseJsonSafe(responseBody) as LoadCodeAssistPayload;
+    }
+    return (await response.json()) as LoadCodeAssistPayload;
+  } catch (error) {
+    console.error("Failed to load Gemini managed project:", error);
+    return null;
+  }
+}
+
+/**
+ * Onboards a managed project for the user, optionally retrying until completion.
+ */
+export async function onboardManagedProject(
+  accessToken: string,
+  tierId: string,
+  projectId?: string,
+  attempts = 10,
+  delayMs = 5000,
+): Promise<string | undefined> {
+  const isFreeTier = tierId === FREE_TIER_ID;
+  const metadata = buildMetadata(projectId, !isFreeTier);
+  const requestBody: Record<string, unknown> = { tierId, metadata };
+
+  if (!isFreeTier) {
+    if (!projectId) {
+      throw new ProjectIdRequiredError();
+    }
+    requestBody.cloudaicompanionProject = projectId;
+  }
+
+  const baseUrl = `${GEMINI_CODE_ASSIST_ENDPOINT}/v1internal`;
+  const onboardUrl = `${baseUrl}:onboardUser`;
+  const headers = {
+    "Content-Type": "application/json",
+    Authorization: `Bearer ${accessToken}`,
+    ...CODE_ASSIST_HEADERS,
+  };
+
+  try {
+    const response = await fetchWithDebug(onboardUrl, "POST", headers, requestBody, projectId);
+    if (!response.ok) {
+      return undefined;
+    }
+
+    let payload = (await response.json()) as OnboardUserPayload;
+    if (!payload.done && payload.name) {
+      for (let attempt = 0; attempt < attempts; attempt += 1) {
+        await wait(delayMs);
+        const operationUrl = `${baseUrl}/${payload.name}`;
+        const opResponse = await fetchWithDebug(operationUrl, "GET", headers, undefined, projectId);
+        if (!opResponse.ok) {
+          return undefined;
+        }
+        payload = (await opResponse.json()) as OnboardUserPayload;
+        if (payload.done) {
+          break;
+        }
+      }
+    }
+
+    const managedProjectId = payload.response?.cloudaicompanionProject?.id;
+    if (payload.done && managedProjectId) {
+      return managedProjectId;
+    }
+    if (payload.done && projectId) {
+      return projectId;
+    }
+  } catch (error) {
+    console.error("Failed to onboard Gemini managed project:", error);
+    return undefined;
+  }
+
+  return undefined;
+}
+
+interface RetrieveUserQuotaBucket {
+  modelId?: string;
+}
+
+interface RetrieveUserQuotaResponse {
+  buckets?: RetrieveUserQuotaBucket[];
+}
+
+/**
+ * Retrieves Code Assist quota buckets, which include model IDs visible to the current account/project.
+ */
+export async function retrieveUserQuota(
+  accessToken: string,
+  projectId: string,
+): Promise<RetrieveUserQuotaResponse | null> {
+  const url = `${GEMINI_CODE_ASSIST_ENDPOINT}/v1internal:retrieveUserQuota`;
+  const headers = {
+    "Content-Type": "application/json",
+    Authorization: `Bearer ${accessToken}`,
+    ...CODE_ASSIST_HEADERS,
+  };
+
+  try {
+    const response = await fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ project: projectId }),
+    });
+
+    if (!response.ok) {
+      return null;
+    }
+    return (await response.json()) as RetrieveUserQuotaResponse;
+  } catch {
+    return null;
+  }
+}
+
+async function fetchWithDebug(
+  url: string,
+  method: "GET" | "POST",
+  headers: Record<string, string>,
+  body: Record<string, unknown> | undefined,
+  projectId?: string,
+): Promise<Response> {
+  const debugContext = startGeminiDebugRequest({
+    originalUrl: url,
+    resolvedUrl: url,
+    method,
+    headers,
+    body: body ? JSON.stringify(body) : undefined,
+    streaming: false,
+    projectId,
+  });
+  const response = await fetch(url, {
+    method,
+    headers,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  if (debugContext) {
+    const responseBody = await readResponseTextIfNeeded(response, true);
+    logGeminiDebugResponse(debugContext, response, { body: responseBody });
+  }
+  return response;
+}
+
+async function readResponseTextIfNeeded(response: Response, needed: boolean): Promise<string | undefined> {
+  if (!needed && response.ok) {
+    return undefined;
+  }
+  try {
+    return await response.clone().text();
+  } catch {
+    return undefined;
+  }
+}