gemini

Documentation

Overview

Package gemini implements native Google OAuth2 authentication for the Gemini Code Assist API, without requiring any external CLI tools.

The flow uses the OAuth 2.0 Authorization Code Grant with PKCE:

1. Start a local HTTP server on a random port
2. Open the browser to Google's authorization URL
3. User authorizes and Google redirects back to the local server
4. Exchange the authorization code for access + refresh tokens
5. Use access token with the Code Assist API

Credentials are stored in the unified auth store (~/.local/share/lokit/auth.json).

OAuth credentials come from the gemini-cli project (installed app, safe to embed per Google's documentation).

Index

• Constants
• Variables
• func AuthCodeFlow(ctx context.Context, onPrompt func(authURL string)) (string, error)
• func DeleteToken() error
• func EnsureAuth(ctx context.Context) (string, error)
• func EnsureAuthWithSetup(ctx context.Context) (*settings.Info, error)
• func IsExpired(info *settings.Info) bool
• func LoadToken() *settings.Info
• func RefreshAccessToken(ctx context.Context, info *settings.Info) error
• func SaveEmail(email string) error
• func SaveProjectID(projectID string) error
• func SaveToken(access, refresh string, expiresAt int64) error
• func SetAuthHeaders(req *http.Request, accessToken string)
• func SetupUser(ctx context.Context, info *settings.Info) (string, error)
• func TokenStatus() string

Constants

const (

	// Code Assist API base — the gemini-cli OAuth client ID is registered
	// for this endpoint, NOT the public generativelanguage.googleapis.com.
	// Using the public API with this client's tokens returns 403
	// ACCESS_TOKEN_SCOPE_INSUFFICIENT.
	CodeAssistBase    = "https://cloudcode-pa.googleapis.com"
	CodeAssistVersion = "v1internal"
)

Variables

var ErrProjectIDRequired = fmt.Errorf("GCP project ID required")

ErrProjectIDRequired is returned by SetupUser when the free tier is unavailable and the user must provide a GCP project ID to use the standard (paid) tier.

Functions

func AuthCodeFlow

func AuthCodeFlow(ctx context.Context, onPrompt func(authURL string)) (string, error)

AuthCodeFlow initiates the Google OAuth2 authorization code flow. It starts a local HTTP server, opens the browser to the authorization URL, and waits for the callback with the auth code. The code is then exchanged for access and refresh tokens.

onPrompt is called with the authorization URL so the caller can display it (in case the browser doesn't open automatically).

Returns the access token on success.

func DeleteToken

func DeleteToken() error

DeleteToken removes the Gemini credentials from the unified auth store.

func EnsureAuth

func EnsureAuth(ctx context.Context) (string, error)

EnsureAuth returns a valid Gemini OAuth access token. It tries, in order:

1. Load existing token; if valid, return it
2. If expired but has refresh token, refresh it
3. If no token or refresh fails, initiate interactive browser auth

func EnsureAuthWithSetup

func EnsureAuthWithSetup(ctx context.Context) (*settings.Info, error)

EnsureAuthWithSetup returns a valid Gemini settings.Info with both a valid access token and a Code Assist project ID. It handles OAuth auth, token refresh, and Code Assist onboarding (loadCodeAssist + onboardUser) as needed.

If ErrProjectIDRequired is returned by SetupUser, this function wraps it with a user-friendly message directing to `lokit auth login --provider gemini`.

func IsExpired

func IsExpired(info *settings.Info) bool

IsExpired returns true if the access token has expired (or will expire within 60 seconds).

func LoadToken

func LoadToken() *settings.Info

LoadToken loads the Gemini OAuth token from the unified auth store. Returns nil if no token is stored.

func RefreshAccessToken

func RefreshAccessToken(ctx context.Context, info *settings.Info) error

RefreshAccessToken uses the refresh token to obtain a new access token. Updates the entry in the unified auth store.

func SaveEmail

func SaveEmail(email string) error

SaveEmail updates the email in the existing gemini entry.

func SaveProjectID

func SaveProjectID(projectID string) error

SaveProjectID updates the project ID in the existing gemini entry.

func SaveToken

func SaveToken(access, refresh string, expiresAt int64) error

SaveToken saves a Gemini OAuth token to the unified auth store. Preserves existing email and projectId if not provided.

func SetAuthHeaders

func SetAuthHeaders(req *http.Request, accessToken string)

SetAuthHeaders sets the required headers for Gemini API requests using OAuth token authentication.

func SetupUser

func SetupUser(ctx context.Context, info *settings.Info) (string, error)

SetupUser performs the Code Assist onboarding flow to get a project ID. If the user is already onboarded, returns the existing project ID. If not, onboards them and polls until complete.

When the free tier is unavailable (e.g. due to location), the standard tier requires a user-provided GCP project ID. If info.ProjectID is already set, it will be used. Otherwise, ErrProjectIDRequired is returned so the caller can prompt the user and retry.

The project ID is saved to the unified auth store.

func TokenStatus

func TokenStatus() string

TokenStatus returns a human-readable status of the stored token.