oauth

type Client struct {
	// ID is the client_id. For Client ID Metadata Documents it is the https
	// URL of the document.
	ID string `json:"id"`
	// Secret is the client_secret of a confidential client; empty for public
	// clients, which authenticate with PKCE alone.
	Secret string `json:"secret,omitempty"`
	// Name is shown on the login page.
	Name string `json:"name"`
	// RedirectURIs are the exact redirect URIs the client may use.
	RedirectURIs []string `json:"redirect_uris"`
	// contains filtered or unexported fields
}

type Config struct {
	// Issuer is the https base URL of this server, without a trailing slash,
	// for example "https://api.acme.com". All endpoints are served under it
	// and it is the issuer reported in the metadata.
	Issuer string
	// Resource is the canonical URL of the MCP endpoint, for example
	// "https://api.acme.com/mcp". Tokens are issued for it alone, and the
	// resource parameter of the code flow must match it.
	Resource string
	// Store keeps clients, pending logins, codes and tokens.
	Store Store
	// Login configures the built-in login page.
	Login Login
	// LoginURL, when set, replaces the built-in page: the browser is sent
	// there with the pending request id in the "request" query parameter.
	// The page must show the ClientName and RedirectHost that Pending
	// returns and get an explicit click from the user before the application
	// calls Approve, so a user is never signed in to a client they did not
	// see.
	LoginURL string
	// Clients are pre-registered clients, for installations that hand out a
	// client id instead of accepting registration from any client.
	Clients []Client
	// AllowedRedirectHosts, when set, restricts dynamic registration and
	// Client ID Metadata Documents to clients whose every redirect URI host
	// (exact match, without port) is listed, for example claude.ai and
	// chatgpt.com, and refuses authorization requests from previously
	// stored clients whose redirect URI is not; empty accepts any host.
	// Config.Clients are not restricted.
	AllowedRedirectHosts []string
	// Fallback, when set, accepts bearer tokens that are not OAuth tokens,
	// for example the "key:secret" form that mcp.BearerToHeaders maps, so
	// clients configured by hand keep working next to OAuth clients. It must
	// fail for tokens that are not its own: an expired OAuth token it
	// accepted would pass Protect, and the client would never get the 401
	// that makes it refresh.
	Fallback func(ctx context.Context, token string) (http.Header, error)
	// AccessTokenTTL bounds access tokens. Defaults to 1h.
	AccessTokenTTL time.Duration
	// RefreshTokenTTL bounds refresh tokens and so the whole connection.
	// Defaults to 30 days.
	RefreshTokenTTL time.Duration
	// OnError, when set, receives the failures users see only as a generic
	// page or a server_error response: Store failures, Challenge and Verify
	// errors that are not shown, and the like. Optional. The context carries
	// the request's values but is never cancelled and has no deadline, and
	// OnError runs synchronously inside the handler, so it must bound its own
	// work.
	OnError func(ctx context.Context, err error)
	// HTTPClient fetches Client ID Metadata Documents. Defaults to a client
	// with a 10s timeout and no proxy that checks every resolved address and
	// refuses loopback, private, link-local, unspecified, multicast,
	// unique-local, carrier-grade NAT, "this network", IETF protocol
	// assignment, benchmarking, class E, NAT64, Teredo and 6to4 addresses; a
	// client set here is trusted to reach any host. Redirects are never
	// followed.
	HTTPClient *http.Client
}

type Grant struct {
	// Subject identifies the user, for example an account id. It is reported
	// to the MCP server as the token user id and never shown to clients.
	Subject string `json:"subject"`
	// Headers are the REST headers that authenticate the user.
	Headers http.Header `json:"headers"`
}

type Login struct {
	// Title names the application on the page.
	Title string
	// IdentifierLabel labels the first field. Defaults to "Email".
	IdentifierLabel string
	// CredentialLabel labels the second field. Defaults to "Password", or
	// "Code" when Challenge is set.
	CredentialLabel string
	// Challenge runs after the identifier is submitted and before the
	// credential is asked, typically to send a one-time code. Errors with
	// code ez.EINVALID, ez.ENOTFOUND or ez.ERESOURCEEXHAUSTED show their
	// message; any other error shows a generic text and goes to OnError.
	Challenge func(ctx context.Context, identifier string) error
	// Verify checks the identifier and the credential and returns the grant
	// for the user. Errors with code ez.ENOTAUTHENTICATED, ez.ENOTFOUND or
	// ez.EINVALID show their message; any other error shows a generic text
	// and goes to OnError.
	Verify func(ctx context.Context, identifier, credential string) (Grant, error)
}

type Pending struct {
	ClientID     string
	ClientName   string
	RedirectHost string
}

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

type Store interface {
	// Put saves value under kind and id until expiresAt, replacing any
	// previous value.
	Put(ctx context.Context, kind, id string, value []byte, expiresAt time.Time) error
	// Get returns the value, or an error with code ez.ENOTFOUND when it is
	// absent or expired.
	Get(ctx context.Context, kind, id string) ([]byte, error)
	// Take returns the value and deletes it in one step, so a code or a
	// refresh token is redeemed at most once. Absent or expired values yield
	// an error with code ez.ENOTFOUND.
	Take(ctx context.Context, kind, id string) ([]byte, error)
	// Delete removes the value. A missing value is not an error.
	Delete(ctx context.Context, kind, id string) error
}