sharkauth

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 11, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package sharkauth provides adapters integrating agent-protocols with SharkAuth, a purpose-built OAuth 2.0 server for agent delegation.

SharkAuth is architecturally aligned with the AAuth protocol, providing:

  • Native RFC 8693 Token Exchange support
  • DPoP (Demonstrating Proof-of-Possession) binding
  • may_act_grants for structured delegation
  • Cascade revocation for delegation chains
  • Grant ID audit trail

Delegation Support

SharkAuth's may_act_grants map directly to AAuth delegation chains: 

client := sharkauth.NewClient("https://auth.example.com")

// Create a delegation grant
grant, err := client.CreateDelegationGrant(ctx, sharkauth.DelegationGrantRequest{
    ActorSubject: "agent:calendar-bot",
    UserSubject:  "user:alice",
    Scopes:       []string{"calendar:read"},
})

DPoP Integration

The package provides DPoP proof generation and verification: 

// Create DPoP proof for a request
proof, err := sharkauth.CreateDPoPProof(privateKey, "POST", tokenEndpoint)

// Use with token exchange
resp, err := client.Exchange(ctx, assertion,
    sharkauth.WithDPoP(proof),
)

Token Exchange

Exchange AAuth assertions for SharkAuth access tokens: 

resp, err := client.ExchangeAAuthToken(ctx, agentToken,
    sharkauth.WithScope("api:read"),
    sharkauth.WithDPoP(proof),
)

References

Index

Constants

View Source 
const (
	// GrantTypeTokenExchange is the OAuth 2.0 token exchange grant type.
	GrantTypeTokenExchange = "urn:ietf:params:oauth:grant-type:token-exchange"

	// TokenTypeJWT is the JWT token type.
	TokenTypeJWT = "urn:ietf:params:oauth:token-type:jwt"

	// TokenTypeAccessToken is the access token type.
	TokenTypeAccessToken = "urn:ietf:params:oauth:token-type:access_token"

	// TokenTypeAAuthAgent is the AAuth agent token type.
	TokenTypeAAuthAgent = "urn:ietf:params:oauth:token-type:aa-agent+jwt"

	// TokenTypeAAuthAuth is the AAuth auth token type.
	TokenTypeAAuthAuth = "urn:ietf:params:oauth:token-type:aa-auth+jwt"
)

Grant types and token types per RFC 8693.

View Source 
const (
	ErrorInvalidRequest       = "invalid_request"
	ErrorInvalidClient        = "invalid_client"
	ErrorInvalidGrant         = "invalid_grant"
	ErrorUnauthorizedClient   = "unauthorized_client"
	ErrorUnsupportedGrantType = "unsupported_grant_type"
	ErrorInvalidScope         = "invalid_scope"
	ErrorAccessDenied         = "access_denied"
	ErrorInvalidDPoP          = "invalid_dpop_proof"
	ErrorUseDPoPNonce         = "use_dpop_nonce"
)

OAuth 2.0 error codes.

Variables

View Source 
var (
	// ErrDiscoveryFailed indicates SharkAuth metadata discovery failed.
	ErrDiscoveryFailed = errors.New("sharkauth: discovery failed")

	// ErrTokenExchangeFailed indicates a token exchange operation failed.
	ErrTokenExchangeFailed = errors.New("sharkauth: token exchange failed")

	// ErrDelegationFailed indicates a delegation grant operation failed.
	ErrDelegationFailed = errors.New("sharkauth: delegation failed")

	// ErrDPoPFailed indicates DPoP proof creation or verification failed.
	ErrDPoPFailed = errors.New("sharkauth: DPoP failed")

	// ErrRevocationFailed indicates a token revocation operation failed.
	ErrRevocationFailed = errors.New("sharkauth: revocation failed")

	// ErrInvalidGrant indicates the grant is invalid or expired.
	ErrInvalidGrant = errors.New("sharkauth: invalid grant")

	// ErrInvalidToken indicates the token is invalid.
	ErrInvalidToken = errors.New("sharkauth: invalid token")

	// ErrUnauthorized indicates the client is not authorized.
	ErrUnauthorized = errors.New("sharkauth: unauthorized")

	// ErrInvalidDPoP indicates the DPoP proof is invalid.
	ErrInvalidDPoP = errors.New("sharkauth: invalid DPoP proof")

	// ErrDPoPRequired indicates DPoP is required but not provided.
	ErrDPoPRequired = errors.New("sharkauth: DPoP required")
)

Package-level errors for SharkAuth adapter operations.

Functions

This section is empty.

Types

type Client 

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

Client provides access to SharkAuth APIs.

func NewClient 

func NewClient(baseURL string, opts ...ClientOption) (*Client, error)

NewClient creates a new SharkAuth client.

func (*Client) BaseURL 

func (c *Client) BaseURL() string

BaseURL returns the SharkAuth base URL.

func (*Client) CreateDelegationGrant 

func (c *Client) CreateDelegationGrant(ctx context.Context, req DelegationGrantRequest) (*DelegationGrant, error)

CreateDelegationGrant creates a new may_act_grant in SharkAuth.

func (*Client) Exchange 

func (c *Client) Exchange(ctx context.Context, subjectToken, subjectTokenType string, opts ...ExchangeOption) (*TokenResponse, error)

Exchange performs a generic token exchange.

func (*Client) ExchangeAAuthToken 

func (c *Client) ExchangeAAuthToken(ctx context.Context, token string, opts ...ExchangeOption) (*TokenResponse, error)

ExchangeAAuthToken exchanges an AAuth token for a SharkAuth access token.

func (*Client) ExchangeWithActor 

func (c *Client) ExchangeWithActor(ctx context.Context, subjectToken, actorToken string, opts ...ExchangeOption) (*TokenResponse, error)

ExchangeWithActor exchanges a token with delegation.

func (*Client) GetDelegationGrant 

func (c *Client) GetDelegationGrant(ctx context.Context, grantID string) (*DelegationGrant, error)

GetDelegationGrant retrieves a delegation grant by ID.

func (*Client) ListDelegationGrants 

func (c *Client) ListDelegationGrants(ctx context.Context, opts ...ListGrantsOption) ([]*DelegationGrant, error)

ListDelegationGrants lists delegation grants for a user or actor.

func (*Client) RevokeDelegationGrant 

func (c *Client) RevokeDelegationGrant(ctx context.Context, grantID string) error

RevokeDelegationGrant revokes a delegation grant and cascades to child grants.

func (*Client) TokenURL 

func (c *Client) TokenURL() string

TokenURL returns the token endpoint URL.

type ClientOption 

type ClientOption func(*clientOptions)

ClientOption configures a Client.

func WithClientCredentials 

func WithClientCredentials(clientID, clientSecret string) ClientOption

WithClientCredentials sets client credentials for authentication.

func WithHTTPClient 

func WithHTTPClient(client *http.Client) ClientOption

WithHTTPClient sets a custom HTTP client.

func WithStaticTokenEndpoint 

func WithStaticTokenEndpoint(url string) ClientOption

WithStaticTokenEndpoint sets a static token endpoint URL.

type DPoPClaims 

type DPoPClaims struct {
	jwt.RegisteredClaims
	HTTPMethod string `json:"htm"`
	HTTPUri    string `json:"htu"`
	Nonce      string `json:"nonce,omitempty"`
	ATH        string `json:"ath,omitempty"` // Access token hash
}

DPoPClaims represents the JWT claims for a DPoP proof per RFC 9449.

func VerifyDPoPProof 

func VerifyDPoPProof(proof, expectedMethod, expectedURI string) (*DPoPClaims, error)

VerifyDPoPProof verifies a DPoP proof against expected values. This is primarily for testing; in production, the authorization server verifies proofs.

type DPoPHeader 

type DPoPHeader struct {
	Type      string          `json:"typ"`
	Algorithm string          `json:"alg"`
	JWK       json.RawMessage `json:"jwk"`
}

DPoPHeader represents the JWT header for a DPoP proof.

type DPoPProof 

type DPoPProof struct {
	// Token is the signed DPoP JWT.
	Token string

	// JTI is the unique token identifier.
	JTI string

	// IssuedAt is when the proof was created.
	IssuedAt time.Time
}

DPoPProof represents a generated DPoP proof.

func CreateDPoPProof 

func CreateDPoPProof(privateKey crypto.Signer, method, uri string, opts ...DPoPProofOption) (*DPoPProof, error)

CreateDPoPProof creates a DPoP proof for a request per RFC 9449.

type DPoPProofOption 

type DPoPProofOption func(*dpopProofOptions)

DPoPProofOption configures DPoP proof generation.

func WithAccessTokenBinding 

func WithAccessTokenBinding(accessToken string) DPoPProofOption

WithAccessTokenBinding binds the proof to an access token (for resource access).

func WithJTI 

func WithJTI(jti string) DPoPProofOption

WithJTI sets a specific JTI for the proof.

func WithNonce 

func WithNonce(nonce string) DPoPProofOption

WithNonce adds a server-provided nonce to the proof.

type DelegationGrant 

type DelegationGrant struct {
	// GrantID is the unique identifier for this grant.
	GrantID string `json:"grant_id"`

	// ActorSubject is the subject that may act (e.g., "agent:calendar-bot").
	ActorSubject string `json:"actor_subject"`

	// UserSubject is the user who granted the delegation (e.g., "user:alice").
	UserSubject string `json:"user_subject"`

	// Scopes are the delegated scopes.
	Scopes []string `json:"scopes"`

	// ExpiresAt is when the grant expires.
	ExpiresAt time.Time `json:"expires_at,omitempty"`

	// CreatedAt is when the grant was created.
	CreatedAt time.Time `json:"created_at"`

	// ParentGrantID links to a parent grant for cascade revocation.
	ParentGrantID string `json:"parent_grant_id,omitempty"`

	// Active indicates if the grant is currently active.
	Active bool `json:"active"`
}

DelegationGrant represents a SharkAuth may_act_grant for agent delegation.

type DelegationGrantRequest 

type DelegationGrantRequest struct {
	// ActorSubject is the agent that will act on behalf of the user.
	ActorSubject string `json:"actor_subject"`

	// UserSubject is the user delegating to the agent.
	UserSubject string `json:"user_subject"`

	// Scopes are the scopes to delegate.
	Scopes []string `json:"scopes"`

	// TTL is the time-to-live for the grant (optional).
	TTL time.Duration `json:"ttl,omitempty"`

	// ParentGrantID links to a parent grant for chain delegation.
	ParentGrantID string `json:"parent_grant_id,omitempty"`
}

DelegationGrantRequest is the request to create a new delegation grant.

type ExchangeOption 

type ExchangeOption func(*exchangeOptions)

ExchangeOption configures a token exchange request.

func WithAudience 

func WithAudience(audience string) ExchangeOption

WithAudience sets the target audience.

func WithDPoP 

func WithDPoP(proof string) ExchangeOption

WithDPoP adds a DPoP proof to the exchange request.

func WithRequestedTokenType 

func WithRequestedTokenType(tokenType string) ExchangeOption

WithRequestedTokenType sets the requested token type.

func WithResource 

func WithResource(resource string) ExchangeOption

WithResource sets the target resource.

func WithScope 

func WithScope(scope string) ExchangeOption

WithScope sets the requested scope.

type ListGrantsOption 

type ListGrantsOption func(*listGrantsOptions)

ListGrantsOption configures grant listing.

func WithActiveOnly 

func WithActiveOnly() ListGrantsOption

WithActiveOnly filters to only active grants.

func WithActorSubject 

func WithActorSubject(subject string) ListGrantsOption

WithActorSubject filters grants by actor subject.

func WithUserSubject 

func WithUserSubject(subject string) ListGrantsOption

WithUserSubject filters grants by user subject.

type TokenErrorResponse 

type TokenErrorResponse struct {
	Error            string `json:"error"`
	ErrorDescription string `json:"error_description,omitempty"`
	ErrorURI         string `json:"error_uri,omitempty"`
}

TokenErrorResponse represents an OAuth 2.0 error response.

type TokenResponse 

type TokenResponse struct {
	// AccessToken is the issued access token.
	AccessToken string `json:"access_token"`

	// IssuedTokenType identifies the type of token issued.
	IssuedTokenType string `json:"issued_token_type"`

	// TokenType is typically "Bearer" or "DPoP".
	TokenType string `json:"token_type"`

	// ExpiresIn is the lifetime in seconds of the access token.
	ExpiresIn int `json:"expires_in,omitempty"`

	// Scope is the scope of the access token.
	Scope string `json:"scope,omitempty"`

	// RefreshToken is an optional refresh token.
	RefreshToken string `json:"refresh_token,omitempty"`

	// GrantID is the SharkAuth grant identifier for audit trail.
	GrantID string `json:"grant_id,omitempty"`
}

TokenResponse represents a token exchange response.

Source Files

View all Source files

Directories

Path Synopsis
examples
aauth command
Package main demonstrates AAuth protocol integration with SharkAuth.
 Package main demonstrates AAuth protocol integration with SharkAuth.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.