oauth2

type AuthRequest struct {
	// Endpoint is the provider's authorization endpoint, e.g.
	// https://idp.example.com/oidc/auth. Take it from
	// [ProviderMetadata.AuthorizationEndpoint] if you used [Discover].
	Endpoint string

	// ClientID identifies the client to the provider. Required.
	ClientID string

	// RedirectURI must match one registered with the provider. Required:
	// omitting it lets a provider fall back to a registered default, which
	// is how a callback ends up somewhere the caller did not intend.
	RedirectURI string

	// Scopes are joined with ScopeSeparator. For OIDC include "openid";
	// add "offline_access" to be issued a refresh token.
	Scopes []string

	// ScopeSeparator joins Scopes into the one scope parameter. Empty means
	// a space, which is RFC 6749 §3.3. Set "," only for a provider that
	// reads scope comma-delimited (Slack's OAuth v2 does); no other value
	// is accepted.
	ScopeSeparator string

	// State is the CSRF token from [NewState]. Required — a flow with no
	// state has no defence against a forged callback.
	State string

	// Challenge is the PKCE challenge from [Verifier.Challenge]. Required.
	Challenge Challenge

	// ResponseType defaults to "code". Set it only for a provider that
	// needs something else; this package can only complete "code".
	ResponseType string

	// Extra carries provider-specific parameters (prompt, audience,
	// resource, login_hint, nonce, ...). Keys that collide with a
	// parameter this package sets are rejected rather than silently
	// dropped or duplicated.
	Extra url.Values
}

type Challenge struct {
	Value  string
	Method Method
}

type Error struct {
	// Code is the OAuth error identifier, e.g. "invalid_grant".
	Code string
	// Description is the provider's human-readable explanation, if any.
	Description string
	// URI optionally points at provider documentation.
	URI string
	// StatusCode is the HTTP status the error arrived with.
	StatusCode int
}

type Exchanger struct {
	// Client performs the request. When nil, a client with
	// DefaultExchangeTimeout is used — never [http.DefaultClient], which
	// has no timeout at all and would let a wedged provider hang a login
	// forever.
	Client HTTPDoer

	// UserAgent is sent as the User-Agent header when non-empty.
	UserAgent string
}

type HTTPDoer interface {
	Do(req *http.Request) (*http.Response, error)
}

type LoopbackLogin struct {
	// AuthorizeEndpoint and TokenEndpoint are the server's two URLs.
	AuthorizeEndpoint string
	TokenEndpoint     string
	// ClientID is the public client (no secret: a CLI cannot keep one).
	ClientID string
	// Scopes requested. The server may grant fewer, and Token.Scope reports
	// what it granted.
	Scopes []string
	// Extra carries additional authorization parameters (e.g. a device
	// label). Reserved names are refused, per AuthRequest.
	Extra url.Values
	// OpenURL launches the browser. When it fails the flow continues: the URL
	// has already been written to Out, so a headless user can open it by hand.
	OpenURL func(string) error
	// Out receives the "open this URL" notice. May be nil.
	Out io.Writer
	// Timeout bounds the wait for the browser to come back. Defaults to 5m.
	Timeout time.Duration
	// HTTPClient performs the token exchange. Nil uses a bounded default.
	HTTPClient HTTPDoer
	// SuccessHTML is the page shown in the browser after the callback. It is
	// shown whether or not the exchange then succeeds, because the exchange
	// happens after the page is served. A default is used when empty.
	SuccessHTML string
}

type Method string

type ProviderMetadata struct {
	Issuer                            string   `json:"issuer"`
	AuthorizationEndpoint             string   `json:"authorization_endpoint"`
	TokenEndpoint                     string   `json:"token_endpoint"`
	UserinfoEndpoint                  string   `json:"userinfo_endpoint,omitempty"`
	JWKSURI                           string   `json:"jwks_uri,omitempty"`
	EndSessionEndpoint                string   `json:"end_session_endpoint,omitempty"`
	ScopesSupported                   []string `json:"scopes_supported,omitempty"`
	ResponseTypesSupported            []string `json:"response_types_supported,omitempty"`
	CodeChallengeMethodsSupported     []string `json:"code_challenge_methods_supported,omitempty"`
	TokenEndpointAuthMethodsSupported []string `json:"token_endpoint_auth_methods_supported,omitempty"`

	Raw map[string]any `json:"-"`
}

type RefreshRequest struct {
	// Endpoint is the provider's token endpoint. Required.
	Endpoint string

	// ClientID must be the client the refresh token was issued to.
	// Required: RFC 6749 §6 requires it for a public client, and a
	// provider that cannot identify the client cannot check the binding.
	ClientID string

	// ClientSecret authenticates a confidential client. Leave it empty for
	// a public client (browser SPA, native app, CLI). When set it is sent
	// in the request body as client_secret.
	ClientSecret string

	// RefreshToken is the credential being redeemed. Required.
	RefreshToken RefreshToken

	// Scopes optionally narrows the granted scope. RFC 6749 §6 permits a
	// scope no broader than the original grant, and providers reject a
	// widening. Leave it nil to keep the original scope, which is what
	// almost every caller wants — omitting the parameter is not the same
	// as sending an empty one, and this package omits it when nil.
	Scopes []string

	// ScopeSeparator joins Scopes, exactly as [AuthRequest.ScopeSeparator]:
	// empty means a space (RFC 6749 §3.3), "," for a comma-delimited
	// provider, and nothing else.
	ScopeSeparator string

	// Extra carries provider-specific body parameters. Keys that collide
	// with a parameter this package sets are rejected.
	Extra url.Values
}

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

type Refreshed struct {
	// Token is the provider's response. Token.RefreshToken holds the raw
	// rotated value when there was one, and is empty when the provider sent
	// none — prefer the RefreshToken field below, which is never empty.
	Token *Token

	// RefreshToken is what to present on the NEXT refresh. It is always
	// populated: the rotated token when the provider issued one, otherwise
	// the token that was just presented. Store it unconditionally.
	RefreshToken RefreshToken

	// Rotated reports whether the provider issued a NEW refresh token and
	// therefore invalidated (or will invalidate) the previous one. It is
	// informational — RefreshToken is already correct either way — and is
	// exposed for callers that log or meter rotation.
	Rotated bool
}

type Token struct {
	AccessToken  string `json:"access_token"`
	TokenType    string `json:"token_type,omitempty"`
	ExpiresIn    int64  `json:"expires_in,omitempty"`
	RefreshToken string `json:"refresh_token,omitempty"`
	IDToken      string `json:"id_token,omitempty"`
	Scope        string `json:"scope,omitempty"`

	// Raw holds every field of the response, including provider-specific
	// ones this struct does not name.
	Raw map[string]any `json:"-"`
}

type TokenRequest struct {
	// Endpoint is the provider's token endpoint. Required.
	Endpoint string

	// ClientID must be the same client the code was issued to. Required.
	ClientID string

	// ClientSecret authenticates a confidential client. Leave it empty for
	// a public client (browser SPA, native app, CLI) — that is what PKCE
	// is for. When set it is sent in the request body as client_secret.
	ClientSecret string

	// RedirectURI must byte-for-byte match the one in the authorization
	// request. Required: providers verify it, and a mismatch is a common
	// cause of an otherwise unexplained invalid_grant.
	RedirectURI string

	// Code is the authorization code from the callback. Required.
	Code string

	// Verifier is the code verifier whose challenge was sent with the
	// authorization request. Required.
	Verifier Verifier

	// Extra carries provider-specific body parameters. Keys that collide
	// with a parameter this package sets are rejected.
	Extra url.Values
}

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