oauth

Documentation

Overview

Package oauth implements OAuth2 authentication flow for Linear API access. It provides a complete OAuth2 implementation including authorization URL generation, callback handling, and secure token exchange.

The package supports both individual user authentication and application-level authentication flows, handling the complexities of OAuth2 state management and PKCE (Proof Key for Code Exchange) for enhanced security.

OAuth2 Flow

The typical OAuth2 flow with this package:

1. Generate authorization URL:

handler := oauth.NewHandler(clientID, clientSecret, redirectURL)
authURL := handler.GetAuthorizationURL(state)

2. User authorizes in browser and is redirected to callback URL

3. Handle callback to exchange code for token:

token, err := handler.HandleCallback(code, state)
if err != nil {
    log.Fatal(err)
}

Security Features

• State parameter validation to prevent CSRF attacks
• Secure token exchange with client credentials
• Automatic cleanup of temporary resources
• Timeout handling for authorization flows

Local Server Mode

For CLI applications, the package can start a temporary local server to handle OAuth callbacks:

token, err := handler.StartOAuthFlow()
if err != nil {
    log.Fatal(err)
}

This automatically:

• Starts a local HTTP server
• Opens the browser to Linear's authorization page
• Handles the callback
• Returns the access token
• Cleans up the server

Error Handling

The package provides detailed error messages for common OAuth issues:

• Invalid authorization codes
• State mismatch (CSRF protection)
• Network failures during token exchange
• Timeout during user authorization

Index

• func GenerateState() string
• type Handler
  • func NewHandler(clientID, clientSecret string) *Handler
  • func NewHandlerWithClient(clientID, clientSecret string, httpClient *http.Client) *Handler
  • func (h *Handler) GetAppAuthorizationURL(redirectURI, state string) string
  • func (h *Handler) GetAuthorizationURL(redirectURI, state string) string
  • func (h *Handler) HandleCallback(port, expectedState string) (string, error)
  • func (h *Handler) HandleCallbackWithFullResponse(port, expectedState string) (*TokenResponse, error)
  • func (h *Handler) RefreshAccessToken(refreshToken string) (*TokenResponse, error)
• type RefresherAdapter
  • func NewRefresherAdapter(handler *Handler) *RefresherAdapter
  • func (a *RefresherAdapter) RefreshAccessToken(refreshToken string) (*token.TokenData, error)
• type TokenResponse
  • func (tr *TokenResponse) ToTokenData() *token.TokenData

Functions

func GenerateState

func GenerateState() string

GenerateState generates a random state parameter for OAuth

Types

type Handler

type Handler struct {
	// contains filtered or unexported fields
}

Handler handles OAuth flow for Linear. It manages the complete OAuth2 authorization code flow including: - Authorization URL generation with CSRF protection - Callback handling with state validation - Secure token exchange

func NewHandler

func NewHandler(clientID, clientSecret string) *Handler

NewHandler creates a new OAuth handler

func NewHandlerWithClient

func NewHandlerWithClient(clientID, clientSecret string, httpClient *http.Client) *Handler

NewHandlerWithClient creates a new OAuth handler with a custom HTTP client

func (*Handler) GetAppAuthorizationURL

func (h *Handler) GetAppAuthorizationURL(redirectURI, state string) string

GetAppAuthorizationURL generates the Linear OAuth authorization URL for app authentication

func (*Handler) GetAuthorizationURL

func (h *Handler) GetAuthorizationURL(redirectURI, state string) string

GetAuthorizationURL generates the Linear OAuth authorization URL for user authentication.

Why include state: The state parameter prevents CSRF attacks by ensuring the callback we receive corresponds to an authorization request we initiated. Linear will include this state in the callback, and we verify it matches.

Scope explanation: - "read": Access to read Linear data (issues, projects, comments) - "write": Ability to create and modify Linear data

func (*Handler) HandleCallback

func (h *Handler) HandleCallback(port, expectedState string) (string, error)

HandleCallback handles the OAuth callback and exchanges code for token. It starts a temporary HTTP server to receive the callback, validates the state parameter for CSRF protection, and exchanges the authorization code for an access token.

Why temporary server: CLI applications can't receive HTTP callbacks directly. We start a local server just long enough to receive the callback, then shut it down immediately after getting the authorization code.

func (*Handler) HandleCallbackWithFullResponse

func (h *Handler) HandleCallbackWithFullResponse(port, expectedState string) (*TokenResponse, error)

HandleCallbackWithFullResponse handles the OAuth callback and returns full token response. This is the new preferred method that captures refresh tokens for automatic token refresh.

func (*Handler) RefreshAccessToken

func (h *Handler) RefreshAccessToken(refreshToken string) (*TokenResponse, error)

RefreshAccessToken uses a refresh token to obtain a new access token. This is called automatically when tokens expire for OAuth apps created after Oct 1, 2025.

type RefresherAdapter

type RefresherAdapter struct {
	// contains filtered or unexported fields
}

RefresherAdapter adapts the OAuth Handler to satisfy the token.OAuthRefresher interface. This avoids circular dependencies between oauth and token packages.

func NewRefresherAdapter

func NewRefresherAdapter(handler *Handler) *RefresherAdapter

NewRefresherAdapter creates an adapter for the OAuth handler

func (*RefresherAdapter) RefreshAccessToken

func (a *RefresherAdapter) RefreshAccessToken(refreshToken string) (*token.TokenData, error)

RefreshAccessToken implements the token.OAuthRefresher interface

type TokenResponse

type TokenResponse struct {
	AccessToken  string `json:"access_token"`
	RefreshToken string `json:"refresh_token,omitempty"`
	TokenType    string `json:"token_type"`
	ExpiresIn    int    `json:"expires_in,omitempty"` // Seconds until expiration
	Scope        string `json:"scope"`
}

TokenResponse represents the response from Linear's token endpoint. For OAuth apps created after Oct 1, 2025, includes refresh_token and expires_in.

func (*TokenResponse) ToTokenData

func (tr *TokenResponse) ToTokenData() *token.TokenData

ToTokenData converts OAuth TokenResponse to storage TokenData format