core

package
v1.0.0-rc.4 Latest Latest
Warning

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

 Go to latest Published: Aug 10, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

Documentation

Overview

Package core implements OAuth 2.0 provider discovery, client authentication, token grants, parsing, and safe native values.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrInvalidExecutor indicates invalid token executor configuration.
	ErrInvalidExecutor = errors.New("invalid OAuth2 token executor")
	// ErrInvalidGrant indicates invalid grant input.
	ErrInvalidGrant = errors.New("invalid OAuth2 grant")
	// ErrInvalidTokenResponse indicates a malformed token endpoint response.
	ErrInvalidTokenResponse = errors.New("invalid OAuth2 token response")
)

Functions

func AuthorizationHeader 

func AuthorizationHeader(token *TokenSet) (map[string]string, error)

AuthorizationHeader returns a canonical Bearer authorization header.

Types

type Client 

type Client struct {
	Provider     *Provider
	ClientID     string
	ClientSecret string
	AuthMethod   ClientAuthMethod
}

Client contains an OAuth provider and the credentials used at its token endpoint.

func NewClient 

func NewClient(provider *Provider, config ClientConfig) (*Client, error)

NewClient constructs and validates an OAuth client.

func (*Client) Clone 

func (c *Client) Clone() *Client

Clone returns a defensive copy of the client and its provider.

func (*Client) Format 

func (c *Client) Format(state fmt.State, _ rune)

Format keeps all fmt formatting variants on the secret-safe representation.

func (*Client) MarshalJSON 

func (c *Client) MarshalJSON() ([]byte, error)

MarshalJSON returns a safe representation of the client.

func (*Client) MarshalMsgpack 

func (c *Client) MarshalMsgpack() ([]byte, error)

MarshalMsgpack serializes a redacted client view.

func (*Client) String 

func (c *Client) String() string

String returns a representation that redacts the client secret.

func (*Client) Validate 

func (c *Client) Validate() error

Validate revalidates the client's exported, mutable configuration.

type ClientAuthMethod 

type ClientAuthMethod string

ClientAuthMethod identifies how an OAuth client authenticates at the token endpoint. 

const (
	// ClientAuthMethodNone sends no client secret.
	ClientAuthMethodNone ClientAuthMethod = "none"
	// ClientAuthMethodBasic sends the client credentials in an Authorization
	// header using the client_secret_basic method.
	ClientAuthMethodBasic ClientAuthMethod = "client_secret_basic"
	// ClientAuthMethodPost sends the client credentials in the form body using
	// the client_secret_post method.
	ClientAuthMethodPost ClientAuthMethod = "client_secret_post"
)

type ClientConfig 

type ClientConfig struct {
	ClientID     string
	ClientSecret string
	AuthMethod   ClientAuthMethod
}

ClientConfig configures an OAuth client.

type ClientCredentialsOptions 

type ClientCredentialsOptions struct {
	Parameters Parameters
	Audience   string
	Scope      []string
	Timeout    time.Duration
}

ClientCredentialsOptions configures a client credentials grant.

type Clock 

type Clock interface {
	Now() time.Time
}

Clock supplies the current time used to calculate token expiry.

type ClockFunc 

type ClockFunc func() time.Time

ClockFunc adapts a function to Clock.

func (ClockFunc) Now 

func (f ClockFunc) Now() time.Time

Now returns the function's current time.

type DiscoveryOptions 

type DiscoveryOptions struct {
	InsecureAllowHTTP bool
	Timeout           time.Duration
}

DiscoveryOptions controls authorization-server metadata discovery.

type Error 

type Error struct {
	Operation   string
	Code        string
	Description string
	URI         string
	StatusCode  int
}

Error is an OAuth protocol error returned by a token endpoint.

func (*Error) Error 

func (e *Error) Error() string

Error returns the OAuth error without request or response bodies.

func (*Error) Format 

func (e *Error) Format(state fmt.State, verb rune)

Format implements fmt.Formatter without exposing raw response data.

func (*Error) MarshalJSON 

func (e *Error) MarshalJSON() ([]byte, error)

MarshalJSON serializes only normalized OAuth error fields.

func (*Error) String 

func (e *Error) String() string

String returns the same secret-free representation as Error.

type Executor 

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

Executor performs OAuth token grants with an injected Ferret HTTP client.

func NewExecutor 

func NewExecutor(httpClient ferrethttp.Client, options ...ExecutorOption) (*Executor, error)

NewExecutor constructs a token grant executor.

func (*Executor) ClientCredentials 

func (e *Executor) ClientCredentials(
	ctx context.Context,
	client *Client,
	options ClientCredentialsOptions,
) (*TokenSet, error)

ClientCredentials exchanges client credentials for a token.

func (*Executor) Refresh 

func (e *Executor) Refresh(
	ctx context.Context,
	client *Client,
	previous *TokenSet,
	options RefreshOptions,
) (*TokenSet, error)

Refresh exchanges a refresh token for a new token set.

func (*Executor) Token 

func (e *Executor) Token(
	ctx context.Context,
	client *Client,
	options TokenOptions,
) (*TokenSet, error)

Token performs an OAuth extension grant. grant_type must appear exactly once in Parameters and must be an absolute URI.

type ExecutorOption 

type ExecutorOption func(*Executor) error

ExecutorOption configures an Executor.

func WithClock 

func WithClock(clock Clock) ExecutorOption

WithClock sets the clock used to calculate token expiry.

type Parameters 

type Parameters map[string][]string

Parameters contains provider-specific form fields. Each value is emitted as a separate form field, preserving repeated parameters.

type Provider 

type Provider struct {
	Issuer                   string
	AuthorizationEndpoint    string
	TokenEndpoint            string
	RevocationEndpoint       string
	IntrospectionEndpoint    string
	JWKSURI                  string
	ScopesSupported          []string
	GrantTypesSupported      []string
	TokenEndpointAuthMethods []string
	// contains filtered or unexported fields
}

Provider describes an OAuth authorization server and its advertised capabilities.

func Discover 

func Discover(
	ctx context.Context,
	httpClient ferrethttp.Client,
	issuer string,
	options DiscoveryOptions,
) (*Provider, error)

Discover loads and validates RFC 8414 authorization-server metadata.

func NewProvider 

func NewProvider(config ProviderConfig) (*Provider, error)

NewProvider constructs and validates an OAuth provider.

func (*Provider) Clone 

func (p *Provider) Clone() *Provider

Clone returns a defensive copy of the provider.

func (*Provider) Format 

func (p *Provider) Format(state fmt.State, _ rune)

Format keeps all fmt formatting variants on the secret-safe representation.

func (*Provider) MarshalJSON 

func (p *Provider) MarshalJSON() ([]byte, error)

MarshalJSON returns the provider's safe public configuration.

func (*Provider) MarshalMsgpack 

func (p *Provider) MarshalMsgpack() ([]byte, error)

MarshalMsgpack serializes the provider's safe public configuration.

func (*Provider) String 

func (p *Provider) String() string

String returns a secret-safe representation of the provider.

func (*Provider) Validate 

func (p *Provider) Validate() error

Validate revalidates the provider's exported, mutable configuration.

type ProviderConfig 

type ProviderConfig struct {
	Issuer                   string
	AuthorizationEndpoint    string
	TokenEndpoint            string
	RevocationEndpoint       string
	IntrospectionEndpoint    string
	JWKSURI                  string
	ScopesSupported          []string
	GrantTypesSupported      []string
	TokenEndpointAuthMethods []string
	InsecureAllowHTTP        bool
}

ProviderConfig configures an OAuth authorization server.

type RefreshOptions 

type RefreshOptions struct {
	Parameters   Parameters
	RefreshToken string
	Scope        []string
	Timeout      time.Duration
}

RefreshOptions configures a refresh token grant.

type TokenOptions 

type TokenOptions struct {
	Parameters Parameters
	Timeout    time.Duration
}

TokenOptions configures an OAuth extension grant.

type TokenSet 

type TokenSet struct {
	ExpiresAt    time.Time
	Extra        map[string]any
	AccessToken  string
	TokenType    string
	RefreshToken string
	Scope        string
	IDToken      string
	ExpiresIn    time.Duration
}

TokenSet represents a token endpoint response.

func (*TokenSet) Clone 

func (t *TokenSet) Clone() *TokenSet

Clone returns an independent copy of the token set.

func (TokenSet) Expired 

func (t TokenSet) Expired(now time.Time, skew time.Duration) bool

Expired reports whether the token is expired at now after applying skew. A token with no known expiry is not considered expired.

func (TokenSet) Format 

func (t TokenSet) Format(state fmt.State, verb rune)

Format implements fmt.Formatter without exposing token material.

func (TokenSet) MarshalJSON 

func (t TokenSet) MarshalJSON() ([]byte, error)

MarshalJSON serializes a redacted, stable token view.

func (TokenSet) MarshalMsgpack 

func (t TokenSet) MarshalMsgpack() ([]byte, error)

MarshalMsgpack serializes a redacted token view.

func (TokenSet) Scopes 

func (t TokenSet) Scopes() []string

Scopes returns the response scope split on ASCII spaces.

func (TokenSet) String 

func (t TokenSet) String() string

String returns a secret-free representation.

func (TokenSet) ValidFor 

func (t TokenSet) ValidFor(now time.Time) (time.Duration, bool)

ValidFor returns the remaining lifetime and whether expiry is known.

Source Files

View all Source files

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.