Documentation
¶
Overview ¶
Package copilot provides OAuth2 Device Flow authentication functionality for GitHub Copilot API. This package implements the complete OAuth2 device flow with GitHub, followed by exchanging the GitHub token for a Copilot API token that expires approximately every 25 minutes.
Package copilot provides authentication and token management functionality for GitHub Copilot API. It handles OAuth2 device flow token storage, serialization, and retrieval for maintaining authenticated sessions with the GitHub Copilot API.
Index ¶
- Constants
- type CopilotAuth
- func (ca *CopilotAuth) CreateTokenStorage(tokenData *CopilotTokenData) *CopilotTokenStorage
- func (ca *CopilotAuth) ExchangeGitHubTokenForCopilot(ctx context.Context, githubToken string) (*CopilotTokenResponse, error)
- func (ca *CopilotAuth) InitiateDeviceFlow(ctx context.Context) (*DeviceCodeResponse, error)
- func (ca *CopilotAuth) PollForGitHubToken(deviceCode string, interval int) (string, error)
- func (ca *CopilotAuth) RefreshCopilotToken(ctx context.Context, githubToken string) (*CopilotTokenData, error)
- func (ca *CopilotAuth) RefreshCopilotTokenWithRetry(ctx context.Context, githubToken string, maxRetries int) (*CopilotTokenData, error)
- func (ca *CopilotAuth) UpdateTokenStorage(storage *CopilotTokenStorage, tokenData *CopilotTokenData)
- type CopilotTokenData
- type CopilotTokenResponse
- type CopilotTokenStorage
- type DeviceCodeResponse
- type GitHubTokenResponse
- type GitHubUserResponse
Constants ¶
const ( // GitHubDeviceCodeURL is the URL for initiating the OAuth 2.0 device authorization flow. GitHubDeviceCodeURL = "https://github.com/login/device/code" // GitHubAccessTokenURL is the URL for exchanging device codes for access tokens. GitHubAccessTokenURL = "https://github.com/login/oauth/access_token" // GitHubCopilotTokenURL is the URL for exchanging GitHub tokens for Copilot tokens. GitHubCopilotTokenURL = "https://api.github.com/copilot_internal/v2/token" // GitHubUserURL is the URL for fetching authenticated user information. GitHubUserURL = "https://api.github.com/user" // GitHubClientID is the official GitHub Copilot Client ID. GitHubClientID = "Iv1.b507a08c87ecfe98" // GitHubScope defines the permissions requested by the application. GitHubScope = "read:user" )
GitHub OAuth Device Flow Constants
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CopilotAuth ¶
type CopilotAuth struct {
// contains filtered or unexported fields
}
CopilotAuth handles GitHub Copilot OAuth2 device flow authentication. It provides methods for the complete authentication flow: device code request, polling for GitHub token, and exchanging for Copilot API token.
func NewCopilotAuth ¶
func NewCopilotAuth(cfg *config.Config) *CopilotAuth
NewCopilotAuth creates a new GitHub Copilot authentication service. It initializes the HTTP client with proxy settings from the configuration.
Parameters:
- cfg: The application configuration containing proxy settings
Returns:
- *CopilotAuth: A new Copilot authentication service instance
func (*CopilotAuth) CreateTokenStorage ¶
func (ca *CopilotAuth) CreateTokenStorage(tokenData *CopilotTokenData) *CopilotTokenStorage
CreateTokenStorage creates a new CopilotTokenStorage from token data.
Parameters:
- tokenData: The Copilot token data
Returns:
- *CopilotTokenStorage: A new token storage instance
func (*CopilotAuth) ExchangeGitHubTokenForCopilot ¶
func (ca *CopilotAuth) ExchangeGitHubTokenForCopilot(ctx context.Context, githubToken string) (*CopilotTokenResponse, error)
ExchangeGitHubTokenForCopilot exchanges a GitHub access token for a Copilot API token. The Copilot token expires approximately every 25 minutes and must be refreshed.
Parameters:
- ctx: The context for the request
- githubToken: The GitHub access token (ghu_xxx)
Returns:
- *CopilotTokenResponse: The Copilot token and metadata
- error: An error if the exchange fails
func (*CopilotAuth) InitiateDeviceFlow ¶
func (ca *CopilotAuth) InitiateDeviceFlow(ctx context.Context) (*DeviceCodeResponse, error)
InitiateDeviceFlow starts the OAuth 2.0 device authorization flow with GitHub. It requests a device code that the user will use to authorize the application.
Parameters:
- ctx: The context for the request
Returns:
- *DeviceCodeResponse: The device code and verification details
- error: An error if the request fails
func (*CopilotAuth) PollForGitHubToken ¶
func (ca *CopilotAuth) PollForGitHubToken(deviceCode string, interval int) (string, error)
PollForGitHubToken polls the GitHub token endpoint to obtain an access token. It follows the OAuth 2.0 device flow polling pattern with proper error handling.
Parameters:
- deviceCode: The device code from InitiateDeviceFlow
- interval: The minimum polling interval in seconds
Returns:
- string: The GitHub access token (ghu_xxx)
- error: An error if polling fails or times out
func (*CopilotAuth) RefreshCopilotToken ¶
func (ca *CopilotAuth) RefreshCopilotToken(ctx context.Context, githubToken string) (*CopilotTokenData, error)
RefreshCopilotToken refreshes the Copilot token using the stored GitHub token. This should be called when the Copilot token is close to expiring (every ~25 minutes).
Parameters:
- ctx: The context for the request
- githubToken: The GitHub access token
Returns:
- *CopilotTokenData: The refreshed Copilot token data
- error: An error if the refresh fails
func (*CopilotAuth) RefreshCopilotTokenWithRetry ¶
func (ca *CopilotAuth) RefreshCopilotTokenWithRetry(ctx context.Context, githubToken string, maxRetries int) (*CopilotTokenData, error)
RefreshCopilotTokenWithRetry attempts to refresh the Copilot token with retry logic.
Parameters:
- ctx: The context for the request
- githubToken: The GitHub access token
- maxRetries: The maximum number of retry attempts
Returns:
- *CopilotTokenData: The refreshed Copilot token data
- error: An error if all retry attempts fail
func (*CopilotAuth) UpdateTokenStorage ¶
func (ca *CopilotAuth) UpdateTokenStorage(storage *CopilotTokenStorage, tokenData *CopilotTokenData)
UpdateTokenStorage updates an existing token storage with new Copilot token data.
Parameters:
- storage: The existing token storage to update
- tokenData: The new Copilot token data
type CopilotTokenData ¶
type CopilotTokenData struct {
// GitHubToken is the GitHub OAuth access token.
GitHubToken string `json:"github_token"`
// CopilotToken is the Copilot API token.
CopilotToken string `json:"copilot_token"`
// CopilotAPIBase is the base URL for Copilot API.
CopilotAPIBase string `json:"copilot_api_base"`
// CopilotExpire is the timestamp when the Copilot token expires.
CopilotExpire string `json:"copilot_expire"`
// Email is the GitHub account email or username.
Email string `json:"email,omitempty"`
// SKU is the subscription type.
SKU string `json:"sku,omitempty"`
}
CopilotTokenData holds Copilot token information.
type CopilotTokenResponse ¶
type CopilotTokenResponse struct {
// Token is the Copilot API bearer token (tid=xxx;exp=xxx;...).
Token string `json:"token"`
// ExpiresAt is the Unix timestamp when the Copilot token expires.
ExpiresAt int64 `json:"expires_at"`
// RefreshIn is the number of seconds until refresh is recommended.
RefreshIn int `json:"refresh_in"`
// Endpoints contains the API endpoints for Copilot services.
Endpoints struct {
API string `json:"api"`
Proxy string `json:"proxy"`
Telemetry string `json:"telemetry"`
} `json:"endpoints"`
// SKU is the Copilot subscription type.
SKU string `json:"sku"`
// ChatEnabled indicates if chat functionality is enabled.
ChatEnabled bool `json:"chat_enabled"`
// Individual indicates if this is an individual subscription.
Individual bool `json:"individual"`
}
CopilotTokenResponse represents the response from GitHub's Copilot token exchange endpoint.
type CopilotTokenStorage ¶
type CopilotTokenStorage struct {
// GitHubToken is the GitHub OAuth access token (ghu_xxx) used to exchange for Copilot tokens.
GitHubToken string `json:"github_token"`
// CopilotToken is the Copilot API token obtained from GitHub token exchange.
// This token expires approximately every 25 minutes and needs to be refreshed.
CopilotToken string `json:"copilot_token"`
// CopilotAPIBase is the base URL for the Copilot API endpoints.
CopilotAPIBase string `json:"copilot_api_base"`
// CopilotExpire is the timestamp when the Copilot token expires.
CopilotExpire string `json:"copilot_expire"`
// LastRefresh is the timestamp of the last Copilot token refresh operation.
LastRefresh string `json:"last_refresh"`
// Email is the GitHub account email address associated with this token.
Email string `json:"email,omitempty"`
// Type indicates the authentication provider type, always "copilot" for this storage.
Type string `json:"type"`
// SKU is the Copilot subscription type (e.g., "free_educational_quota", "copilot_individual").
SKU string `json:"sku,omitempty"`
}
CopilotTokenStorage stores OAuth2 token information for GitHub Copilot API authentication. It maintains both the GitHub access token and the derived Copilot token with their respective expiration times.
func (*CopilotTokenStorage) SaveTokenToFile ¶
func (ts *CopilotTokenStorage) SaveTokenToFile(authFilePath string) error
SaveTokenToFile serializes the Copilot token storage to a JSON file. This method creates the necessary directory structure and writes the token data in JSON format to the specified file path for persistent storage.
Parameters:
- authFilePath: The full path where the token file should be saved
Returns:
- error: An error if the operation fails, nil otherwise
type DeviceCodeResponse ¶
type DeviceCodeResponse struct {
// DeviceCode is the code that the client uses to poll for an access token.
DeviceCode string `json:"device_code"`
// UserCode is the code that the user enters at the verification URI.
UserCode string `json:"user_code"`
// VerificationURI is the URL where the user can enter the user code to authorize the device.
VerificationURI string `json:"verification_uri"`
// ExpiresIn is the time in seconds until the device_code and user_code expire.
ExpiresIn int `json:"expires_in"`
// Interval is the minimum time in seconds that the client should wait between polling requests.
Interval int `json:"interval"`
}
DeviceCodeResponse represents the response from GitHub's device authorization endpoint.
type GitHubTokenResponse ¶
type GitHubTokenResponse struct {
// AccessToken is the GitHub access token (ghu_xxx).
AccessToken string `json:"access_token"`
// TokenType indicates the type of token, typically "bearer".
TokenType string `json:"token_type"`
// Scope defines the permissions granted by the token.
Scope string `json:"scope"`
// Error contains error code if the request failed.
Error string `json:"error,omitempty"`
// ErrorDescription provides human-readable error details.
ErrorDescription string `json:"error_description,omitempty"`
}
GitHubTokenResponse represents the successful token response from GitHub's token endpoint.
type GitHubUserResponse ¶
type GitHubUserResponse struct {
// Login is the GitHub username.
Login string `json:"login"`
// Email is the user's public email address (may be empty if private).
Email string `json:"email"`
// Name is the user's display name.
Name string `json:"name"`
// ID is the unique GitHub user ID.
ID int64 `json:"id"`
}
GitHubUserResponse represents the response from GitHub's user API endpoint.