Documentation
¶
Index ¶
- func DecodeSessionIDFromState(state string) (string, error)
- func GenerateStateWithSessionID(sessionID string) (string, error)
- func OpenBrowser(ctx context.Context, urlToOpen string) error
- func SetGlobalCallbackServer(server *CallbackServer)
- func ValidateAndSanitizeURL(rawURL string) (string, error)
- type AuthorizationRequiredError
- type CallbackResult
- type CallbackServer
- type Manager
- type ManagerOption
- type StateData
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DecodeSessionIDFromState ¶
DecodeSessionIDFromState extracts the session ID from an OAuth state parameter.
This function is used by OAuth callback handlers to decode session IDs. When the OAuth provider redirects back to our callback endpoint, they include the state parameter we originally sent. This function reverses the encoding done by GenerateStateWithSessionID to extract the session ID, allowing us to route the authorization code back to the correct agent session that initiated the OAuth flow.
This is the critical piece that bridges the browser-based OAuth callback back to the specific runtime session that needs the authorization.
func GenerateStateWithSessionID ¶
GenerateStateWithSessionID generates an OAuth state parameter that encodes the session ID.
OAuth State Parameter Design:
When an agent needs OAuth authorization, the flow works like this: 1. Agent runtime detects OAuth is needed and pauses execution 2. We generate authorization URL with state parameter containing the session ID 3. User's browser is redirected to the OAuth provider for authorization 4. OAuth provider redirects back to our callback URL with the authorization code AND the state 5. Our callback handler receives the state, extracts the session ID from it 6. We can then resume the correct agent session with the authorization code
Without encoding session ID in state, we couldn't match the OAuth callback to the specific agent session that requested authorization, especially in multi-session scenarios.
The state parameter combines: - Session ID: To route the callback back to the correct session - Random bytes: For CSRF protection (traditional OAuth security requirement)
func OpenBrowser ¶
OpenBrowser opens the default browser to the specified URL with security validation.
This function now includes security measures to prevent command injection and malicious URL schemes. All URLs are validated before being passed to system commands to ensure they are safe to open.
Security features: - URL validation and sanitization using ValidateAndSanitizeURL - Logging of security events (blocked URLs, successful opens) - Maintains backward compatibility for legitimate OAuth URLs
func SetGlobalCallbackServer ¶ added in v1.5.6
func SetGlobalCallbackServer(server *CallbackServer)
SetGlobalCallbackServer sets the global callback server instance
func ValidateAndSanitizeURL ¶ added in v1.5.1
ValidateAndSanitizeURL validates and sanitizes a URL for safe browser opening.
This function implements security measures to prevent command injection and malicious URL schemes based on security best practices outlined in the Veria Labs article on MCP to shell vulnerabilities.
Security validations: - Only allows http:// and https:// schemes (blocks javascript:, data:, file:, etc.) - Validates URL format using Go's net/url package - Prevents command injection by ensuring URL can be safely passed to system commands
Returns the original URL if valid, or an error if the URL fails security validation.
Types ¶
type AuthorizationRequiredError ¶
AuthorizationRequiredError wraps an OAuth authorization error with server information
func (*AuthorizationRequiredError) Error ¶
func (e *AuthorizationRequiredError) Error() string
func (*AuthorizationRequiredError) Unwrap ¶
func (e *AuthorizationRequiredError) Unwrap() error
type CallbackResult ¶ added in v1.5.6
CallbackResult contains the result of an OAuth callback
type CallbackServer ¶ added in v1.5.6
type CallbackServer struct {
// contains filtered or unexported fields
}
CallbackServer handles OAuth callback redirects for CLI/TUI mode
func GetGlobalCallbackServer ¶ added in v1.5.6
func GetGlobalCallbackServer() *CallbackServer
GetGlobalCallbackServer returns the global callback server instance
func NewCallbackServer ¶ added in v1.5.6
func NewCallbackServer(port int) *CallbackServer
NewCallbackServer creates a new OAuth callback server
func (*CallbackServer) GetRedirectURI ¶ added in v1.5.6
func (s *CallbackServer) GetRedirectURI() string
GetRedirectURI returns the redirect URI for this callback server
func (*CallbackServer) Start ¶ added in v1.5.6
func (s *CallbackServer) Start(ctx context.Context) error
Start starts the OAuth callback server
func (*CallbackServer) Stop ¶ added in v1.5.6
func (s *CallbackServer) Stop(ctx context.Context) error
Stop stops the OAuth callback server
func (*CallbackServer) WaitForCallback ¶ added in v1.5.6
func (s *CallbackServer) WaitForCallback(ctx context.Context) (CallbackResult, error)
WaitForCallback waits for an OAuth callback with timeout
type Manager ¶
type Manager interface {
// ExecuteWithOAuth wraps an operation that may require OAuth authorization with automatic retry logic.
// If the operation fails with an OAuth authorization error, it handles the OAuth flow and retries the operation.
// Returns the error from the operation or from the OAuth flow if it fails.
ExecuteWithOAuth(ctx context.Context, sessionID string, operation func() error) error
// StartAuthorizationFlow signals that user confirmation has been given to start the OAuth flow
StartAuthorizationFlow(ctx context.Context, confirmation bool)
// SendAuthorizationCode sends the OAuth authorization code and state after user has completed the OAuth flow
SendAuthorizationCode(ctx context.Context, code, state string) error
// UpdateEmitCallback updates the callback function for emitting auth events
UpdateEmitCallback(emitAuthRequired func(serverURL, serverType, status string))
// Cleanup stops any owned resources like callback servers
Cleanup(ctx context.Context) error
}
Manager defines the contract for OAuth flow management
func NewManager ¶
func NewManager(emitAuthRequired func(serverURL, serverType, status string), opts ...ManagerOption) Manager
NewManager creates a new OAuth manager with optional port configuration
type ManagerOption ¶ added in v1.5.8
type ManagerOption func(*manager)
ManagerOption configures the OAuth manager
func WithManagedServer ¶ added in v1.5.10
func WithManagedServer(managed bool) ManagerOption
func WithPort ¶ added in v1.5.8
func WithPort(port int) ManagerOption
WithPort sets the callback server port
func WithRedirectURI ¶ added in v1.5.8
func WithRedirectURI(uri string) ManagerOption
WithRedirectURI sets a custom redirect URI
type StateData ¶
type StateData struct {
SessionID string `json:"session_id"` // The session ID that initiated the OAuth flow
Random string `json:"random"` // Random component for CSRF protection
}
StateData represents the data encoded in the OAuth state parameter.
In OAuth flows, the state parameter serves dual purposes:
- Security: CSRF protection by including random data
- Session tracking: When the browser returns from authorization, we need to know which session triggered the OAuth flow to route the callback correctly.
Since OAuth authorization happens in a browser (different context from our runtime), we embed the session ID in the state parameter so we can retrieve it when the authorization server redirects back to us with the authorization code.
Source Files