Documentation
¶
Overview ¶
Package auth provides browser-based authentication for the StackEye CLI.
This package handles the OAuth-like flow for CLI authentication:
- Start a local callback server on a random port
- Open the user's browser to the StackEye web UI /cli-auth page
- Wait for the callback with the API key
- Return the authentication result
The actual API key storage is handled by the stackeye-go-sdk/config package. This package only handles the browser flow mechanics.
Usage:
result, err := auth.BrowserLogin(auth.Options{
APIURL: "https://api.stackeye.io",
Timeout: 5 * time.Minute,
})
if err != nil {
return err
}
fmt.Printf("Logged in as org: %s\n", result.OrgName)
Package auth provides browser-based authentication for the StackEye CLI.
Example ¶
Example shows basic usage of the auth package.
result, err := BrowserLogin(Options{
APIURL: "https://api.stackeye.io",
Timeout: 5 * time.Minute,
SkipBrowserOpen: true, // Skip browser in tests
OnBrowserOpen: func(url string) {
fmt.Printf("Please visit: %s\n", url)
},
OnWaiting: func() {
fmt.Println("Waiting for authentication...")
},
})
if err != nil {
fmt.Printf("Login failed: %v\n", err)
return
}
fmt.Printf("Logged in to org: %s\n", result.OrgName)
Index ¶
Examples ¶
Constants ¶
const ( // DefaultTimeout is the maximum time to wait for the browser callback. DefaultTimeout = 5 * time.Minute // DefaultAPIURL is the production API endpoint. DefaultAPIURL = "https://api.stackeye.io" )
Default configuration values.
Variables ¶
var ( // ErrTimeout is returned when the browser callback times out. ErrTimeout = errors.New("auth: login timed out waiting for browser callback") // ErrCanceled is returned when the login is canceled. ErrCanceled = errors.New("auth: login canceled") // ErrInvalidAPIKey is returned when the received API key is invalid. ErrInvalidAPIKey = errors.New("auth: received invalid API key format") // ErrMissingAPIKey is returned when the callback is missing the API key. ErrMissingAPIKey = errors.New("auth: callback missing api_key parameter") // ErrForbidden is returned when a non-localhost request is received. ErrForbidden = errors.New("auth: request from non-localhost IP rejected") )
Common errors returned by this package.
Functions ¶
func APIURLToWebURL ¶
APIURLToWebURL converts an API URL to the corresponding web UI URL.
Transformations based on actual infrastructure:
- api.stackeye.io -> app.stackeye.io (production)
- api-dev.stackeye.io -> app-dev.stackeye.io
- api-staging.stackeye.io -> app-staging.stackeye.io
For non-standard URLs (e.g., localhost, custom domains), returns unchanged.
func BuildWebUIURL ¶
BuildWebUIURL constructs the web UI authentication URL.
Parameters:
- apiURL: The API URL (e.g., "https://api.stackeye.io")
- callbackURL: The local callback URL (e.g., "http://127.0.0.1:12345/callback")
Returns the full web UI URL with the callback parameter.
func IsLocalhost ¶
IsLocalhost checks if an IP address is a localhost address. Accepts both IPv4 (127.x.x.x) and IPv6 (::1) localhost addresses.
func OpenBrowser ¶
OpenBrowser opens the specified URL in the default browser. Returns an error if the browser cannot be opened.
Types ¶
type Options ¶
type Options struct {
// APIURL is the StackEye API URL to authenticate against.
// If empty, defaults to DefaultAPIURL.
APIURL string
// Timeout is the maximum time to wait for the browser callback.
// If zero, defaults to DefaultTimeout.
Timeout time.Duration
// OnBrowserOpen is called when the browser is about to be opened.
// If nil, a default message is printed to stdout.
OnBrowserOpen func(url string)
// OnWaiting is called while waiting for the browser callback.
// If nil, a default message is printed to stdout.
OnWaiting func()
// SkipBrowserOpen prevents the actual browser from opening.
// Useful for testing - the OnBrowserOpen callback is still called.
SkipBrowserOpen bool
}
Options configures the browser login flow.
type Result ¶
type Result struct {
// APIKey is the generated API key for CLI authentication.
APIKey string
// OrgID is the organization ID associated with the API key.
OrgID string
// OrgName is the organization name associated with the API key.
OrgName string
}
Result holds the authentication result from a successful browser login.
func BrowserLogin ¶
BrowserLogin performs browser-based authentication.
This function:
- Starts a local HTTP server on a random port
- Opens the browser to the StackEye web UI /cli-auth page
- Waits for the callback with the API key
- Returns the authentication result
The caller is responsible for storing the API key using the config package.
Source Files