Documentation
¶
Index ¶
- func DecodeSessionIDFromState(state string) (string, error)
- func GenerateStateWithSessionID(sessionID string) (string, error)
- func MayBeOAuthError(err error) (error, bool)
- func OpenBrowser(urlToOpen string) error
- func ValidateAndSanitizeURL(rawURL string) (string, error)
- type AuthorizationRequiredError
- type Manager
- type ServerInfoProvider
- 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 MayBeOAuthError ¶ added in v1.3.6
MayBeOAuthError checks if the given error is an OAuth authorization error and wraps it with server information if available.
This function examines error chains to identify OAuth authorization errors wrapped within agent ToolSetError (or any other future error that might contain a possible OAuth error). When found, it extracts server information and returns a properly wrapped AuthorizationRequiredError.
Returns: - wrapped error and true if this is an OAuth authorization error - original error and false otherwise
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 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 Manager ¶
type Manager interface {
// HandleAuthorizationFlow handles a single OAuth authorization flow
HandleAuthorizationFlow(ctx context.Context, sessionID string, oauthErr *AuthorizationRequiredError) error
// StartAuthorizationFlow signals that user confirmation has been given to start the OAuth flow
StartAuthorizationFlow(confirmation bool)
// SendAuthorizationCode sends the OAuth authorization code after user has completed the OAuth flow
SendAuthorizationCode(code string) error
}
Manager defines the contract for OAuth flow management
func NewManager ¶
NewManager creates a new OAuth manager
type ServerInfoProvider ¶
type ServerInfoProvider interface {
GetServerInfo() (serverURL, serverType string)
}
ServerInfoProvider interface for toolsets that can provide server information
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