client

Documentation

Overview

Package client provides a Go SDK for agents to interact with AgentAuth servers.

The client supports both ID-JAG (automated) and AAuth (human consent) authorization flows.

Example usage for ID-JAG flow:

client := client.New("https://authz.example.com")
token, err := client.ExchangeIDJAG(ctx, idJagAssertion, "read:email read:profile")

Example usage for AAuth flow:

client := client.New("https://authz.example.com")
token, err := client.RequestAuthorization(ctx, &client.AuthorizationRequest{
    AgentToken:  agentToken,
    UserID:      "user-123",
    Scopes:      "write:profile",
    MissionName: "Update Profile",
})

Index

• type AuthorizationRequest
• type AuthorizationResult
• type Client
  • func New(baseURL string, opts ...Option) *Client
  • func (c *Client) CacheToken(key string, token *Token)
  • func (c *Client) ClearCache()
  • func (c *Client) ExchangeIDJAG(ctx context.Context, assertion, scope string) (*Token, error)
  • func (c *Client) ExchangeJWTBearer(ctx context.Context, assertion, scope string) (*Token, error)
  • func (c *Client) GetCachedToken(key string) *Token
  • func (c *Client) Introspect(ctx context.Context, token string) (*IntrospectionResult, error)
  • func (c *Client) PollConsentStatus(ctx context.Context, statusURI string) (*AuthorizationResult, error)
  • func (c *Client) RefreshToken(ctx context.Context, refreshToken, scope string) (*Token, error)
  • func (c *Client) RequestAuthorization(ctx context.Context, req *AuthorizationRequest) (*AuthorizationResult, error)
  • func (c *Client) RequestAuthorizationAndWait(ctx context.Context, req *AuthorizationRequest) (*Token, error)
  • func (c *Client) Revoke(ctx context.Context, token, tokenTypeHint string) error
  • func (c *Client) WaitForConsent(ctx context.Context, statusURI string) (*Token, error)
• type IntrospectionResult
• type Option
  • func WithHTTPClient(httpClient *http.Client) Option
  • func WithPollInterval(interval time.Duration) Option
  • func WithPollTimeout(timeout time.Duration) Option
• type Token
  • func (t *Token) IsExpired() bool
  • func (t *Token) IsExpiringSoon(within time.Duration) bool

Types

type AuthorizationRequest

type AuthorizationRequest struct {
	AgentToken      string `json:"agent_token"`
	UserID          string `json:"user_id"`
	Scopes          string `json:"scope"`
	MissionName     string `json:"mission_name,omitempty"`
	MissionDesc     string `json:"mission_description,omitempty"`
	InteractionType string `json:"interaction_type,omitempty"`
	Duration        int64  `json:"duration,omitempty"`
	RedirectURI     string `json:"redirect_uri,omitempty"`
	State           string `json:"state,omitempty"`
}

AuthorizationRequest is a request for authorization via AAuth.

type AuthorizationResult

type AuthorizationResult struct {
	// Status is "approved", "denied", "pending", or "expired"
	Status string

	// Token is set if the authorization was approved
	Token *Token

	// ConsentURI is set if human consent is required
	ConsentURI string

	// StatusURI is set if human consent is required (for polling)
	StatusURI string

	// MissionID identifies the pending mission
	MissionID string

	// Error information if the request failed
	Error     string
	ErrorDesc string
}

AuthorizationResult contains the result of an authorization request.

type Client

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

Client provides methods to interact with AgentAuth servers.

func New

func New(baseURL string, opts ...Option) *Client

New creates a new AgentAuth client.

func (*Client) CacheToken

func (c *Client) CacheToken(key string, token *Token)

CacheToken stores a token in the client's cache.

func (*Client) ClearCache

func (c *Client) ClearCache()

ClearCache removes all cached tokens.

func (*Client) ExchangeIDJAG

func (c *Client) ExchangeIDJAG(ctx context.Context, assertion, scope string) (*Token, error)

ExchangeIDJAG exchanges an ID-JAG assertion for an access token. This uses the RFC 8693 token exchange protocol.

func (*Client) ExchangeJWTBearer

func (c *Client) ExchangeJWTBearer(ctx context.Context, assertion, scope string) (*Token, error)

ExchangeJWTBearer exchanges a JWT bearer assertion for an access token. This uses the RFC 7523 JWT bearer grant type.

func (*Client) GetCachedToken

func (c *Client) GetCachedToken(key string) *Token

GetCachedToken retrieves a non-expired token from the cache. Returns nil if the token is not found or expired.

func (*Client) Introspect

func (c *Client) Introspect(ctx context.Context, token string) (*IntrospectionResult, error)

Introspect checks if a token is valid and returns its metadata.

func (*Client) PollConsentStatus

func (c *Client) PollConsentStatus(ctx context.Context, statusURI string) (*AuthorizationResult, error)

PollConsentStatus polls the status URI once and returns the current status.

func (*Client) RefreshToken

func (c *Client) RefreshToken(ctx context.Context, refreshToken, scope string) (*Token, error)

RefreshToken refreshes an access token using a refresh token.

func (*Client) RequestAuthorization

func (c *Client) RequestAuthorization(ctx context.Context, req *AuthorizationRequest) (*AuthorizationResult, error)

RequestAuthorization requests authorization via the AAuth flow. If pre-authorized, returns immediately with a token. If consent is required, returns a result with ConsentURI for the user to visit.

func (*Client) RequestAuthorizationAndWait

func (c *Client) RequestAuthorizationAndWait(ctx context.Context, req *AuthorizationRequest) (*Token, error)

RequestAuthorizationAndWait requests authorization and waits for consent if needed. This is a convenience method that combines RequestAuthorization with PollConsentStatus. It blocks until the user approves/denies or the timeout is reached.

func (*Client) Revoke

func (c *Client) Revoke(ctx context.Context, token, tokenTypeHint string) error

Revoke invalidates an access or refresh token.

func (*Client) WaitForConsent

func (c *Client) WaitForConsent(ctx context.Context, statusURI string) (*Token, error)

WaitForConsent polls the status URI until consent is granted or denied. It respects the client's pollInterval and pollTimeout settings.

type IntrospectionResult

type IntrospectionResult struct {
	Active    bool           `json:"active"`
	Scope     string         `json:"scope,omitempty"`
	ClientID  string         `json:"client_id,omitempty"`
	Username  string         `json:"username,omitempty"`
	TokenType string         `json:"token_type,omitempty"`
	Exp       int64          `json:"exp,omitempty"`
	Iat       int64          `json:"iat,omitempty"`
	Sub       string         `json:"sub,omitempty"`
	Aud       string         `json:"aud,omitempty"`
	Iss       string         `json:"iss,omitempty"`
	Act       map[string]any `json:"act,omitempty"`
}

IntrospectionResult contains token introspection data.

type Option

type Option func(*Client)

Option configures the Client.

func WithHTTPClient

func WithHTTPClient(httpClient *http.Client) Option

WithHTTPClient sets a custom HTTP client.

func WithPollInterval

func WithPollInterval(interval time.Duration) Option

WithPollInterval sets the interval for polling consent status.

func WithPollTimeout

func WithPollTimeout(timeout time.Duration) Option

WithPollTimeout sets the maximum time to wait for consent.

type Token

type Token struct {
	AccessToken  string    `json:"access_token"`
	TokenType    string    `json:"token_type"`
	ExpiresIn    int       `json:"expires_in"`
	Scope        string    `json:"scope,omitempty"`
	RefreshToken string    `json:"refresh_token,omitempty"`
	ExpiresAt    time.Time `json:"-"`
}

Token represents an access token with metadata.

func (*Token) IsExpired

func (t *Token) IsExpired() bool

IsExpired returns true if the token has expired.

func (*Token) IsExpiringSoon

func (t *Token) IsExpiringSoon(within time.Duration) bool

IsExpiringSoon returns true if the token expires within the given duration.