oauth

README

OAuth Implementation Notes

ID Type Handling

The Laravel API returns numeric IDs (integers) for users and organizations, while the Go client needs to handle these appropriately:

• User IDs: int64 in Go, numeric in Laravel
• Organization IDs: int64 in Go, numeric in Laravel
• Organization slugs: Laravel uses ulid field, mapped to Slug in Go structs

Design Decision

We chose to have the Go client adapt to the Laravel API's natural types rather than forcing the API to return strings for numeric data. This follows the principle that the API should define the contract, and clients should adapt to it.

JSON Mapping

type Organization struct {
    ID   int64  `json:"id"`       // Numeric ID from Laravel
    Slug string `json:"ulid"`     // Laravel's ulid field mapped to Slug
    Name string `json:"name"`
}

This approach:

• Keeps the Laravel API idiomatic (numeric IDs)
• Makes the Go client properly handle the API contract
• Avoids unnecessary type conversions on the server
• Maintains type safety in both languages

Documentation

Index

• func GenerateState() (string, error)
• type AuthFlow
  • func (af *AuthFlow) Run(ctx context.Context, am *config.AccountManager) error
• type CallbackServer
  • func NewCallbackServer(expectedState string) *CallbackServer
  • func (s *CallbackServer) FindAvailablePort() (string, error)
  • func (s *CallbackServer) GetCallbackURL() string
  • func (s *CallbackServer) Start(ctx context.Context) error
• type Organization
• type OrganizationResponse
• type PKCEChallenge
  • func GeneratePKCEChallenge() (*PKCEChallenge, error)

Functions

func GenerateState

func GenerateState() (string, error)

GenerateState generates a random state parameter for CSRF protection

Types

type AuthFlow

type AuthFlow struct {
	BaseURL       string
	CallbackPort  string
	NoBrowser     bool
	IsInteractive bool
	// contains filtered or unexported fields
}

AuthFlow handles the complete OAuth2 authentication flow

func (*AuthFlow) Run

func (af *AuthFlow) Run(ctx context.Context, am *config.AccountManager) error

Run executes the OAuth2 authentication flow

type CallbackServer

type CallbackServer struct {
	Port          string
	AuthCode      chan string
	AuthError     chan error
	AuthState     string
	ExpectedState string
}

CallbackServer handles OAuth2 callback

func NewCallbackServer

func NewCallbackServer(expectedState string) *CallbackServer

NewCallbackServer creates a new callback server

func (*CallbackServer) FindAvailablePort

func (s *CallbackServer) FindAvailablePort() (string, error)

FindAvailablePort finds an available port for the callback server. The listener is bound to 127.0.0.1 so the OAuth callback is reachable only from the local machine; no LAN exposure.

func (*CallbackServer) GetCallbackURL

func (s *CallbackServer) GetCallbackURL() string

GetCallbackURL returns the callback URL for this server

func (*CallbackServer) Start

func (s *CallbackServer) Start(ctx context.Context) error

Start starts the callback server

type Organization

type Organization struct {
	ID   string `json:"id"`   // ULID comes in ID field from API
	ULID string `json:"ulid"` // Not used but kept for compatibility
	Name string `json:"name"`
}

Organization represents an organization the user has access to

type OrganizationResponse

type OrganizationResponse struct {
	Organizations []Organization `json:"organizations"`
}

OrganizationResponse represents the API response for user organizations

type PKCEChallenge

type PKCEChallenge struct {
	Verifier  string
	Challenge string
	Method    string
}

PKCEChallenge represents a PKCE challenge pair

func GeneratePKCEChallenge

func GeneratePKCEChallenge() (*PKCEChallenge, error)

GeneratePKCEChallenge creates a new PKCE challenge pair