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"`

	// 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"`
}

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 BrowserLoginConfig 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.
	CallbackPort int

	// 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
}

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 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

	// 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"`
}

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"`

	// 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 DeleteRegistrationRequest struct {
	RegistrationClientURI   string
	RegistrationAccessToken string
	// HTTPClient — see GetRegistrationRequest for rationale.
	HTTPClient *http.Client
}

type DeleteRegistrationResponse struct{}

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 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 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 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"`
}

type TokenEndpointAuthMethod 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
}