client

type ASMetadata struct {
	// Required
	Issuer        string `json:"issuer"`
	TokenEndpoint string `json:"token_endpoint"`

	// Recommended
	AuthorizationEndpoint string `json:"authorization_endpoint,omitempty"`
	JWKSURI               string `json:"jwks_uri,omitempty"`

	// Optional
	RegistrationEndpoint        string `json:"registration_endpoint,omitempty"`
	IntrospectionEndpoint       string `json:"introspection_endpoint,omitempty"`
	RevocationEndpoint          string `json:"revocation_endpoint,omitempty"`
	UserinfoEndpoint            string `json:"userinfo_endpoint,omitempty"`
	DeviceAuthorizationEndpoint string `json:"device_authorization_endpoint,omitempty"` // RFC 8628 §4

	// Supported features
	ScopesSupported                            []string `json:"scopes_supported,omitempty"`
	ResponseTypesSupported                     []string `json:"response_types_supported,omitempty"`
	GrantTypesSupported                        []string `json:"grant_types_supported,omitempty"`
	CodeChallengeMethodsSupported              []string `json:"code_challenge_methods_supported,omitempty"`
	TokenEndpointAuthMethods                   []string `json:"token_endpoint_auth_methods_supported,omitempty"`
	TokenEndpointAuthSigningAlgValuesSupported []string `json:"token_endpoint_auth_signing_alg_values_supported,omitempty"`

	// DPoPSigningAlgValuesSupported lists the JWS algorithms the server
	// accepts on a DPoP proof (RFC 9449 §5.1). Its presence is how a
	// client learns the server supports DPoP at all. Check a key against
	// it with DPoPKey.SupportedBy before sending proofs.
	DPoPSigningAlgValuesSupported []string `json:"dpop_signing_alg_values_supported,omitempty"`

	// AuthorizationResponseIssParameterSupported surfaces the RFC 9207
	// advertisement value from the AS metadata document. Pointer semantics
	// are load-bearing for the §2.4 enforcement rules a consumer applies
	// after `BrowserLoginRequest.OnCallback` runs:
	//
	//   - non-nil pointing to true  → AS commits to including `iss` on every
	//     authorization response; a callback with empty `iss` MUST be rejected.
	//   - non-nil pointing to false → AS explicitly disclaims support;
	//     consumers may skip iss enforcement (legacy-AS posture).
	//   - nil (field absent)        → AS predates RFC 9207 / didn't advertise;
	//     consumers may treat as legacy-AS unless a stricter policy (e.g.
	//     FAPI 2.0) demands enforcement regardless.
	//
	// The distinction between explicit false and absent is preserved so a
	// strict-mode validator can tell "AS told us no" from "AS didn't say."
	//
	// RFC 9207 §3:
	//   https://www.rfc-editor.org/rfc/rfc9207#section-3
	AuthorizationResponseIssParameterSupported *bool `json:"authorization_response_iss_parameter_supported,omitempty"`

	// ClientIdMetadataDocumentSupported surfaces the SEP-991 / Client ID
	// Metadata Document advertisement
	// (draft-ietf-oauth-client-id-metadata-document): when true the AS
	// accepts a URL as the client_id and resolves the metadata document
	// itself, so clients SHOULD prefer that over Dynamic Client
	// Registration. Absent and explicit false are equivalent here (no
	// enforcement rule keys off the distinction), so a plain bool suffices.
	ClientIdMetadataDocumentSupported bool `json:"client_id_metadata_document_supported,omitempty"`
}

type ASMetadataStore interface {
	// Get returns the cached metadata for an issuer if present and not expired.
	// Returns (nil, false) on cache miss or expiry.
	Get(issuer string) (*ASMetadata, bool)

	// Put stores metadata for an issuer with the given TTL. A TTL of 0 means
	// use the store's default. Put replaces any existing entry for the issuer.
	Put(issuer string, md *ASMetadata, ttl time.Duration)
}

type AuthClient struct {

	// OnToken is an optional callback invoked after a successful token
	// refresh (the refresh_token grant path through refreshTokenLocked).
	// It fires AFTER the new credential has been stored via CredentialStore,
	// so consumers can use the callback for side-effects (logging, metrics,
	// external persistence) that should observe the post-refresh state.
	//
	// Thread safety: the callback is invoked synchronously from whichever
	// goroutine triggered the refresh. Implementations must be thread-safe
	// if the AuthClient is shared across goroutines.
	//
	// Lock contract: the callback runs while the AuthClient internal mutex
	// is held — same as CredentialStore.SetCredential. Callbacks must NOT
	// re-enter AuthClient methods (GetToken, GetCredential, Login,
	// refreshTokenLocked) or they will deadlock. Callbacks should be
	// lightweight and non-blocking.
	//
	// Does NOT fire for initial logins (Login, LoginWithBrowser) — those
	// return the credential directly to the caller, who can persist it
	// explicitly. Only the automatic refresh_token grant path fires this.
	OnToken func(*ServerCredential)
	// contains filtered or unexported fields
}

type AuthTransport struct {
	Base  http.RoundTripper
	Token string
}

type AuthorizeError struct {
	Status      int
	Code        string
	Description string
	Body        string
}

type BrowserLoginRequest struct {
	// AuthorizationEndpoint is the AS authorization URL.
	// If empty, auto-discovered via DiscoverAS(serverURL) using the
	// AuthClient's server URL.
	AuthorizationEndpoint string

	// TokenEndpoint is the AS token URL for code exchange.
	// If empty, uses the AuthClient's configured tokenEndpoint.
	TokenEndpoint string

	// ClientID identifies this client to the authorization server.
	// Required.
	ClientID string

	// Scopes to request (e.g., []string{"openid", "read", "write"}).
	Scopes []string

	// CallbackPort is the port for the loopback redirect server.
	// If 0, a random available port is chosen. Ignored when Listener or
	// RedirectURI is set.
	CallbackPort int

	// Listener, when set, is the loopback listener the callback is served
	// on, in place of one LoginWithBrowser binds itself. A caller doing DCR
	// binds it first, registers LoopbackRedirectURI(l.Addr()) (or its own
	// RedirectURI), and hands it over, so the port registered is the port
	// served with no release-and-rebind window in between.
	//
	// LoginWithBrowser takes ownership: it closes the listener before
	// returning, on every path including early validation errors. A
	// listener serves one login.
	Listener net.Listener

	// RedirectURI, when set, is sent byte-for-byte as redirect_uri on the
	// authorization request and the code exchange, and the callback is
	// served on its path. Use it when the registered redirect differs from
	// LoopbackRedirectURI's default, e.g. an IP literal (which RFC 8252 §8.3
	// prefers over "localhost") or a path other than /callback.
	//
	// It must be an http URI on a loopback host (localhost, 127.0.0.1 or
	// [::1]) with an explicit port. With Listener set the port must equal
	// the listener's; without one, LoginWithBrowser binds the URI's host
	// and port. Anything else fails before the browser opens.
	//
	// See: https://www.rfc-editor.org/rfc/rfc8252#section-7.3
	RedirectURI string

	// Timeout for the entire flow (waiting for user to complete browser login).
	// Defaults to 5 minutes.
	Timeout time.Duration

	// OpenBrowser is called to open the authorization URL in the user's browser.
	// If nil, uses the platform default (open/xdg-open/start).
	// Set to a custom function for testing or headless environments.
	OpenBrowser func(url string) error

	// HTTPClient is used for the token exchange request.
	// If nil, uses http.DefaultClient.
	HTTPClient *http.Client

	// Resource is the RFC 8707 resource indicator — the canonical URI of the
	// target resource server (e.g., "https://api.example.com"). When set, it's
	// included in both the authorization request and token exchange to bind the
	// token to a specific audience. MCP spec requires this parameter.
	//
	// See: https://www.rfc-editor.org/rfc/rfc8707
	Resource string

	// ClientSecret is the client's secret for confidential clients.
	// If empty, the client is treated as a public client (auth method "none")
	// and only client_id is sent in the token exchange.
	// When set, the auth method is negotiated based on AS metadata
	// (token_endpoint_auth_methods_supported) per RFC 6749 §2.3.
	//
	// See: https://github.com/panyam/oneauth/issues/72
	ClientSecret string

	// TokenEndpointAuthMethods specifies the auth methods supported by the AS
	// token endpoint (e.g., ["client_secret_post", "client_secret_basic"]).
	// This is used when AuthorizationEndpoint and TokenEndpoint are explicitly
	// provided and discovery is skipped — without this field, the client
	// defaults to client_secret_basic which may not be what the AS supports.
	//
	// Callers that perform their own AS discovery (e.g., via PRM → AS metadata)
	// should pass token_endpoint_auth_methods_supported here so the client
	// negotiates the correct auth method per RFC 6749 §2.3.
	//
	// If empty and discovery is skipped, defaults to client_secret_basic
	// per RFC 6749 §2.3.1.
	//
	// See: https://www.rfc-editor.org/rfc/rfc6749#section-2.3
	// See: https://github.com/panyam/oneauth/issues/74
	TokenEndpointAuthMethods []string

	// ClientAssertion, when non-nil, switches the code-exchange step to
	// private_key_jwt client authentication (RFC 7521 §4.2 / RFC 7523
	// §2.2 / OIDC Core §9). The client signs a fresh JWT with the
	// configured private key and presents it as `client_assertion`
	// instead of using ClientSecret. Mutually exclusive with
	// ClientSecret — when both are set, ClientAssertion wins.
	ClientAssertion *ClientAssertionConfig

	// OnCallback, when non-nil, fires after the loopback receives the
	// authorization-code redirect and after state validation, but BEFORE
	// the token exchange. Consumers use it to apply per-policy validation
	// of the RFC 9207 `iss` query parameter (which oneauth surfaces but
	// deliberately does not enforce — the spec leaves enforcement to the
	// client per §2.4). Returning a non-nil error aborts the flow and the
	// error is returned (wrapped) from LoginWithBrowser; no token exchange
	// is performed.
	OnCallback func(ctx context.Context, params CallbackParams) error
}

type BrowserOpenError struct {
	URL string
	Err error
}

type CallbackError struct {
	Code        string
	Description string
}

type CallbackParams struct {
	// Iss is the RFC 9207 `iss` query parameter — the issuer identifier of
	// the authorization response. Empty when the AS does not send it (legacy
	// ASes pre-dating RFC 9207). Consumers MAY treat absence as a hard
	// failure for high-assurance flows; oneauth itself does not enforce.
	Iss string

	// Code is the OAuth 2.0 `code` query parameter (the authorization code
	// to be exchanged at the token endpoint). Non-empty by the time the
	// hook fires.
	Code string

	// State is the OAuth 2.0 `state` query parameter as echoed back by the
	// AS. Already validated against the client-issued state before the hook
	// fires — exposed for logging / audit only.
	State string
}

type ClientAssertionConfig struct {
	// PrivateKey is the asymmetric signing key — *rsa.PrivateKey or
	// *ecdsa.PrivateKey. Must match the public key registered with the
	// AS via DCR (RFC 7591) for the same `client_id`.
	PrivateKey crypto.PrivateKey

	// SigningAlg is the JWS alg value: "RS256" or "ES256". Must match
	// the alg the AS registered for this client.
	SigningAlg string

	// KeyID, when non-empty, is set as the `kid` JWS header so the AS
	// can disambiguate among multiple registered keys for the same
	// client. Optional — clients with a single key may leave it blank.
	KeyID string

	// Lifetime is how long the minted assertion is valid for. Defaults
	// to 60s (recommended ceiling for FAPI / most IdPs). Must be ≤
	// 5min to satisfy OneAuth's server-side assertion lifetime cap;
	// other AS implementations are typically stricter.
	Lifetime time.Duration

	// Audience, when non-empty, overrides the `aud` claim of the minted
	// assertion. Empty falls back to the positional `audience` argument
	// of MintClientAssertion (typically the token endpoint URL).
	//
	// RFC 7523bis (current OAuth WG draft) requires `aud` to be the AS
	// issuer identifier; OIDC Core §9 historically permitted the token
	// endpoint URL. ASes in the wild differ — set this when targeting a
	// 7523bis-strict AS that rejects the token endpoint URL.
	Audience string
}

type ClientCredentialsRequest struct {
	// ClientID identifies the client to the AS. Required.
	ClientID string

	// ClientSecret authenticates the client when ClientAssertion is nil.
	// Sent via the negotiated client_secret_basic / client_secret_post
	// method (RFC 6749 §2.3.1).
	ClientSecret string

	// ClientAssertion, when non-nil, switches client authentication to
	// the private_key_jwt path (RFC 7521 §4.2 / RFC 7523 §2.2 / OIDC
	// Core §9). ClientSecret is ignored when this is set.
	ClientAssertion *ClientAssertionConfig

	// Scopes requested for the access token. Sent as the space-delimited
	// `scope` form value.
	Scopes []string

	// Resources are RFC 8707 resource indicators — absolute URIs naming
	// the resource server(s) the token will be used at. Emitted as
	// repeated `resource` form values per §2.
	Resources []string

	// AuthorizationDetails carries RFC 9396 rich authorization
	// requirements. JSON-encoded into a single `authorization_details`
	// form value per §6.1.
	AuthorizationDetails []core.AuthorizationDetail
}

type ClientCredentialsSource struct {
	// TokenEndpoint is the authorization server's token URL.
	TokenEndpoint string

	// ClientID identifies this client to the authorization server.
	ClientID string

	// ClientSecret authenticates this client when ClientAssertion is nil.
	// Sent via the negotiated client_secret_basic or client_secret_post
	// method (RFC 6749 §2.3.1).
	ClientSecret string

	// ClientAssertion, when non-nil, switches the source to the
	// private_key_jwt client-authentication path (RFC 7521 §4.2 /
	// RFC 7523 §2.2 / OIDC Core §9). ClientSecret is ignored. The same
	// caching, OnToken, and ProactiveRefresher machinery applies.
	ClientAssertion *ClientAssertionConfig

	// Scopes to request.
	Scopes []string

	// Resources are RFC 8707 resource indicators forwarded on every
	// token request. Emitted as repeated `resource` form values per §2.
	Resources []string

	// AuthorizationDetails are RFC 9396 rich authorization requirements
	// forwarded on every token request as the `authorization_details`
	// JSON-encoded form value per §6.1.
	AuthorizationDetails []core.AuthorizationDetail

	// Refresher enables proactive token refresh before expiry. When nil or
	// Refresher.Buffer == 0, refresh is reactive — happens on the next
	// Token() call after expiry.
	//
	// Typical values: Buffer of 30s-60s for tokens with 5-15 minute lifetimes.
	// The goroutine starts lazily on the first Token() call and runs until
	// Close() is called on the source.
	Refresher *ProactiveRefresher

	// OnToken is an optional callback invoked after every successful token
	// acquisition — both the initial fetch and all subsequent refreshes
	// (reactive and proactive). Use this to persist the credential to an
	// external store (file, database) without implementing a full
	// CredentialStore.
	//
	// Thread safety: the callback may be invoked from the caller's
	// goroutine (initial/reactive path) or from the background refresh
	// goroutine (proactive path). Implementations must be thread-safe.
	//
	// The callback holds no locks of the source, so calling back into
	// Token() from within the callback is safe (but useless — it will
	// return the same token that was just passed in).
	//
	// The credential passed to the callback is the same value returned
	// from AuthClient.ClientCredentialsToken. Mutating it from within the
	// callback is not safe.
	OnToken func(*ServerCredential)
	// contains filtered or unexported fields
}

type ClientOption func(*AuthClient)

type ClientRegistrationRequest struct {
	ClientID                string   `json:"client_id,omitempty"`
	ClientName              string   `json:"client_name"`
	ClientURI               string   `json:"client_uri,omitempty"`
	RedirectURIs            []string `json:"redirect_uris"`
	GrantTypes              []string `json:"grant_types,omitempty"`
	ResponseTypes           []string `json:"response_types,omitempty"`
	TokenEndpointAuthMethod string   `json:"token_endpoint_auth_method,omitempty"`
	Scope                   string   `json:"scope,omitempty"`
	// ApplicationType identifies the client class per OpenID Connect Dynamic
	// Client Registration 1.0 §2: "native" for installed/CLI/SDK clients,
	// "web" for web-server-hosted clients. omitempty so existing callers stay
	// wire-compatible; consumers whose spec requires it (e.g. MCP per SEP-837)
	// set it explicitly.
	ApplicationType string `json:"application_type,omitempty"`
	// DPoPBoundAccessTokens asks the AS to always issue this client
	// DPoP-bound access tokens and to refuse its token requests that
	// carry no proof (RFC 9449 §5.2).
	DPoPBoundAccessTokens bool `json:"dpop_bound_access_tokens,omitempty"`

	// RequirePushedAuthorizationRequests asks the AS to accept this
	// client's authorization requests only through PAR (RFC 9126 §6).
	RequirePushedAuthorizationRequests bool `json:"require_pushed_authorization_requests,omitempty"`
}

type ClientRegistrationResponse struct {
	ClientID                string   `json:"client_id"`
	ClientSecret            string   `json:"client_secret,omitempty"`
	ClientIDIssuedAt        int64    `json:"client_id_issued_at,omitempty"`
	ClientSecretExpiresAt   int64    `json:"client_secret_expires_at,omitempty"`
	ClientName              string   `json:"client_name,omitempty"`
	ClientURI               string   `json:"client_uri,omitempty"`
	RedirectURIs            []string `json:"redirect_uris,omitempty"`
	GrantTypes              []string `json:"grant_types,omitempty"`
	TokenEndpointAuthMethod string   `json:"token_endpoint_auth_method,omitempty"`
	Scope                   string   `json:"scope,omitempty"`

	// DPoPBoundAccessTokens is the AS's record of the RFC 9449 §5.2
	// setting. An AS that ignores the field leaves it false.
	DPoPBoundAccessTokens bool `json:"dpop_bound_access_tokens,omitempty"`

	// RequirePushedAuthorizationRequests is the AS's record of RFC 9126 §6
	// require_pushed_authorization_requests for this client.
	RequirePushedAuthorizationRequests bool `json:"require_pushed_authorization_requests,omitempty"`

	// RFC 7592 §3 — management credentials. RegistrationClientURI is the
	// management endpoint for this specific registration; RegistrationAccessToken
	// is the Bearer token that authorizes calls against it.
	RegistrationAccessToken string `json:"registration_access_token,omitempty"`
	RegistrationClientURI   string `json:"registration_client_uri,omitempty"`
}

type CredentialStore interface {
	// GetCredential retrieves a credential for a server URL
	// Returns nil, nil if no credential exists for the server
	GetCredential(serverURL string) (*ServerCredential, error)

	// SetCredential stores a credential for a server URL
	SetCredential(serverURL string, cred *ServerCredential) error

	// RemoveCredential removes a credential for a server URL
	RemoveCredential(serverURL string) error

	// ListServers returns all server URLs with stored credentials
	ListServers() ([]string, error)

	// Save persists any pending changes (for stores that batch writes)
	Save() error
}

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

type DeleteRegistrationRequest struct {
	RegistrationClientURI   string
	RegistrationAccessToken string
	// HTTPClient — see GetRegistrationRequest for rationale.
	HTTPClient *http.Client
}

type DeleteRegistrationResponse struct{}

type DeviceAuthorizationRequest struct {
	// ClientID is the OAuth client identifier. Required.
	ClientID string

	// ClientSecret authenticates a confidential client to the
	// device_authorization endpoint. Empty for public clients.
	ClientSecret string

	// Scopes is the list of OAuth scopes to request. Empty omits the
	// `scope` form value entirely (AS-default scope set).
	Scopes []string

	// Audience populates the RFC 8707 `audience` form value when set.
	Audience string
}

type DeviceAuthorizationResponse struct {
	// DeviceCode is the high-entropy code the device polls with.
	DeviceCode string `json:"device_code"`

	// UserCode is the short, human-typeable code the user enters on the
	// verification URI. Already formatted by the AS (e.g. "WDJB-MJHT").
	UserCode string `json:"user_code"`

	// VerificationURI is the URL the user opens to enter the user_code.
	VerificationURI string `json:"verification_uri"`

	// VerificationURIComplete is the convenience URL with the user_code
	// pre-encoded as a query parameter (RFC 8628 §3.3.1). Empty when the
	// AS doesn't advertise this field; clients SHOULD prefer it when
	// rendering a QR code or opening a browser.
	VerificationURIComplete string `json:"verification_uri_complete,omitempty"`

	// ExpiresIn is the seconds until the device_code expires.
	ExpiresIn int64 `json:"expires_in"`

	// Interval is the AS-advised minimum polling interval in seconds.
	// Clients MUST respect this; the AS may raise it via slow_down.
	Interval int `json:"interval,omitempty"`
}

type DiscoveryOption func(*discoveryConfig)

type GetRegistrationRequest struct {
	// RegistrationClientURI is the management endpoint returned at
	// registration time (RFC 7592 §3 registration_client_uri).
	RegistrationClientURI string
	// RegistrationAccessToken authorizes calls to RegistrationClientURI
	// (RFC 7592 §3).
	RegistrationAccessToken string
	// HTTPClient is used to make the request. nil → http.DefaultClient.
	// Conceptually this is a transport option (analog of gRPC CallOption);
	// it lives on the request struct so the method retains a strict
	// (ctx, req) → (resp, err) signature.
	HTTPClient *http.Client
}

type GetRegistrationResponse struct {
	Registration *ClientRegistrationResponse
}

type JwtBearerGrantRequest struct {
	// ClientID identifies the client to the AS. Required.
	ClientID string

	// ClientSecret authenticates the client when ClientAssertion is nil.
	ClientSecret string

	// ClientAssertion, when non-nil, switches client authentication to
	// the private_key_jwt path. The resulting `client_assertion` form
	// field coexists with the bearer `assertion` below.
	ClientAssertion *ClientAssertionConfig

	// Assertion is the signed JWT presented as the authorization grant
	// (RFC 7523 §2.1). Required. Issued out-of-band — typically the
	// output of a prior token exchange or a trusted upstream IdP.
	Assertion string

	// Scope optionally narrows the requested scopes for the issued
	// access token. Space-delimited on the wire per RFC 6749 §3.3.
	Scope []string

	// Resources are RFC 8707 resource indicators emitted as repeated
	// `resource` form values.
	Resources []string
}

type LoginRequest struct {
	// Username is the resource-owner identifier (email / username).
	Username string

	// Password is the resource-owner secret.
	Password string

	// Scope is the requested OAuth scope (space-delimited).
	Scope string

	// ClientID identifies the client. Defaults to "cli" when empty.
	ClientID string

	// ClientSecret authenticates a confidential client to the token
	// endpoint per RFC 6749 §2.3.1 (client_secret_basic / _post).
	// Required by Keycloak (and most production ASes) when the client
	// is registered as confidential; ignored on the legacy
	// /auth/cli/token path. Empty for public clients (which use PKCE
	// rather than a secret).
	ClientSecret string
}

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

type OAuth2TokenRequest struct {
	GrantType    string `json:"grant_type"`
	Username     string `json:"username,omitempty"`
	Password     string `json:"password,omitempty"`
	RefreshToken string `json:"refresh_token,omitempty"`
	Scope        string `json:"scope,omitempty"`
	ClientID     string `json:"client_id,omitempty"`
	ClientSecret string `json:"client_secret,omitempty"`
	Code         string `json:"code,omitempty"`          // For authorization_code grant
	CodeVerifier string `json:"code_verifier,omitempty"` // PKCE verifier for authorization_code grant
	RedirectURI  string `json:"redirect_uri,omitempty"`  // Redirect URI for authorization_code grant
}

type OAuth2TokenResponse struct {
	AccessToken          string `json:"access_token"`
	TokenType            string `json:"token_type"`
	ExpiresIn            int64  `json:"expires_in"`
	RefreshToken         string `json:"refresh_token,omitempty"`
	Scope                string `json:"scope,omitempty"`
	AuthorizationDetails []any  `json:"authorization_details,omitempty"` // RFC 9396 (raw JSON)
	Error                string `json:"error,omitempty"`
	ErrorDesc            string `json:"error_description,omitempty"`
}

type PollDeviceTokenRequest struct {
	// DeviceCode is the device_code from DeviceAuthorizationResponse.
	DeviceCode string

	// ClientID is the OAuth client identifier. Required.
	ClientID string

	// ClientSecret authenticates a confidential client (issue 266 — the
	// AS REQUIRES this when the client is registered confidential).
	ClientSecret string
}

type ProactiveRefresher struct {
	// Buffer is how long before token expiry to refresh. Must be positive
	// to enable proactive refresh. A buffer of 30s means the refresh fires
	// 30 seconds before the token would have expired reactively.
	Buffer time.Duration
	// contains filtered or unexported fields
}

type RefreshTokenRequest struct {
	// ClientID identifies the client to the AS. Required.
	ClientID string

	// ClientSecret authenticates the client. Optional — public clients
	// (PKCE-grant origin) leave it empty. When set, the auth method is
	// negotiated from the AS metadata (client_secret_basic vs
	// client_secret_post) per RFC 6749 §2.3, mirroring ClientCredentials.
	ClientSecret string

	// RefreshToken is the long-lived token issued by a prior grant.
	// Required.
	RefreshToken string

	// Scopes, when non-empty, narrows the access-token scope to a subset
	// of the original grant per RFC 6749 §6. Omitted from the form when
	// empty (the AS reuses the original scope set).
	Scopes []string
}

type ScopeAwareTokenSource interface {
	TokenSource
	TokenForScopes(scopes []string) (string, error)
}

type ServerCredential struct {
	AccessToken          string                     `json:"access_token"`
	RefreshToken         string                     `json:"refresh_token,omitempty"`
	TokenType            string                     `json:"token_type,omitempty"`
	UserID               string                     `json:"user_id,omitempty"`
	UserEmail            string                     `json:"user_email,omitempty"`
	Scope                string                     `json:"scope,omitempty"`
	AuthorizationDetails []core.AuthorizationDetail `json:"authorization_details,omitempty"` // RFC 9396
	ExpiresAt            time.Time                  `json:"expires_at"`
	CreatedAt            time.Time                  `json:"created_at"`

	// ClientID is the client the token was issued to. Automatic refresh
	// presents it, since the AS only redeems a refresh token for the
	// client it was issued to (RFC 6749 §6). Empty in credentials stored
	// by older SDK versions, where refresh falls back to "cli".
	ClientID string `json:"client_id,omitempty"`
}

type TokenEndpointAuthMethod string

type TokenError struct {
	Status      int
	Code        string
	Description string
	// contains filtered or unexported fields
}

type TokenExchangeRequest struct {
	// ClientID identifies the client to the AS. Required.
	ClientID string

	// ClientSecret authenticates the client when ClientAssertion is nil.
	ClientSecret string

	// ClientAssertion, when non-nil, switches client authentication to
	// the private_key_jwt path (RFC 7521 §4.2 / RFC 7523 §2.2).
	ClientAssertion *ClientAssertionConfig

	// SubjectToken carries the security token representing the party on
	// whose behalf the request is made. Required (RFC 8693 §2.1).
	SubjectToken string

	// SubjectTokenType identifies the kind of the SubjectToken (e.g.
	// urn:ietf:params:oauth:token-type:id_token). Required.
	SubjectTokenType string

	// ActorToken is an optional second token identifying the acting
	// party — used in delegation flows where the actor differs from the
	// subject (RFC 8693 §1.2).
	ActorToken string

	// ActorTokenType identifies the kind of the ActorToken. Required
	// when ActorToken is set.
	ActorTokenType string

	// RequestedTokenType identifies the kind of token the caller wants
	// the AS to issue. Optional — when omitted the AS chooses.
	RequestedTokenType string

	// Audience names the relying parties intended to consume the
	// issued token (RFC 8693 §2.1). Emitted as repeated `audience`
	// form values when more than one is provided.
	Audience []string

	// Resource is the RFC 8707 resource indicator. Emitted as repeated
	// `resource` form values per §2.
	Resource []string

	// Scope requests specific scopes for the issued token. Encoded as a
	// single space-delimited `scope` form value per RFC 6749 §3.3.
	Scope []string
}

type TokenExchangeResponse struct {
	AccessToken     string
	IssuedTokenType string
	TokenType       string
	ExpiresIn       int
	RefreshToken    string
	Scope           []string
}

type TokenSource interface {
	Token() (string, error)
}

type UpdateRegistrationRequest struct {
	RegistrationClientURI   string
	RegistrationAccessToken string
	// ClientID is the client's existing client_id. Required by RFC 7592 §2.2;
	// auto-filled into Metadata.ClientID by the SDK before sending if the
	// caller hasn't already set it.
	ClientID string
	// Metadata is the full RFC 7591/7592 client metadata that will replace
	// the existing registration. Treated as a full replacement (not PATCH).
	Metadata ClientRegistrationRequest
	// HTTPClient — see GetRegistrationRequest for rationale.
	HTTPClient *http.Client
}

type UpdateRegistrationResponse struct {
	Registration *ClientRegistrationResponse
}