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. An http
	// URI on a loopback host also accepts any port on the same hostname,
	// path and query (RFC 8252 7.3), so http://localhost/callback admits
	// http://localhost:3118/callback.
	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
	// TokenPrefix names the tokens of this server, for example "acme": access
	// tokens are "acmeat_...", refresh tokens "acmert_...". It must match
	// ^[a-z0-9]{2,10}$ so both prefixes fit the 12 characters
	// components/auth/token allows. Pick one that no other token of the
	// application starts with, so AuthFunc, Protect and Verify tell OAuth
	// tokens apart by their shape alone.
	TokenPrefix 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. A refusal calls Deny and sends the browser to the URL it
	// returns, which carries access_denied.
	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, decides whether a bearer token that is not shaped
	// like an access token of this server may reach the MCP endpoint, for
	// example an API key of the application, so clients configured by hand
	// keep working next to OAuth clients. It returns true to accept the
	// token and false to refuse it; an error means the token could not be
	// checked, such as a Store outage, and is reported to OnError: Protect
	// answers 500 and AuthFunc returns the error. AuthFunc passes an
	// accepted token to the REST API unchanged, which authenticates it
	// again: Fallback only answers at the MCP edge. It must refuse tokens
	// that are not its own: any token it accepted passes Protect, and a
	// client holding a bad token would never get the 401 that starts
	// discovery. Tokens shaped like access tokens never reach it.
	Fallback func(ctx context.Context, token string) (bool, error)
	// AccessTokenTTL bounds access tokens. Defaults to 1h.
	AccessTokenTTL time.Duration
	// RefreshTokenTTL bounds refresh tokens and so the whole connection,
	// from the code exchange on: a rotation keeps the expiry of its family.
	// Defaults to 30 days. Never puts no fixed end on the connection: it
	// lives until the client goes IdleTTL without refreshing or reuses a
	// rotated token, each rotation moving the family's expiry to IdleTTL
	// from then.
	RefreshTokenTTL time.Duration
	// IdleTTL is how long a connection under RefreshTokenTTL Never lives
	// after its last refresh. It is kept with the family when issued, so a
	// later change applies to new connections only. Ignored under a finite
	// RefreshTokenTTL, which bounds the connection by itself. Defaults to
	// 30 days. Never is rejected.
	IdleTTL time.Duration
	// RequestTTL bounds a pending login, from authorize to approval.
	// Defaults to 10 minutes.
	RequestTTL time.Duration
	// CodeTTL bounds an authorization code until it is exchanged. Defaults
	// to 1 minute.
	CodeTTL time.Duration
	// RegisteredClientTTL keeps a dynamically registered client once a user
	// has approved it. Each authorize, and each code or refresh exchange
	// before its tokens are written, stores the approved client again with a
	// fresh expiry, so only clients unused for this long expire, even under a
	// longer RefreshTokenTTL. Defaults to 365 days.
	RegisteredClientTTL time.Duration
	// UnusedClientTTL keeps a dynamically registered client that no user has
	// approved yet: registration stores it for this long, and each authorize
	// extends it to this long from then and no further, so a registration
	// nobody completes a login with expires UnusedClientTTL after its last
	// authorize (or its registration, without one). The first code
	// exchange approves the client and gives it RegisteredClientTTL. It must
	// cover a whole login: New rejects a value below RequestTTL plus CodeTTL.
	// Defaults to 7 days.
	UnusedClientTTL time.Duration
	// MetadataCacheTTL is how long a fetched Client ID Metadata Document is
	// cached, regardless of its Cache-Control. Defaults to 1h.
	MetadataCacheTTL time.Duration
	// RefreshTimeout bounds the Store calls of a refresh, which run detached
	// from the request so a client that disconnects cannot stop them halfway:
	// reading the token and its family, renewing the client, writing the new
	// tokens, the Swap or the revocation. Defaults to 10s.
	RefreshTimeout time.Duration
	// MaxLoginAttempts is how many failed Challenge or Verify calls void a
	// pending request on the built-in login page. Defaults to 5.
	MaxLoginAttempts int
	// RegistrationLimit is how many dynamic registration requests one client
	// address may make per minute; the ones after it are answered 429 with
	// Retry-After and store nothing. Every registration POST counts, refused
	// and malformed ones too; the CORS preflight does not. Defaults to 20: a
	// client registers once when a user connects it, and hosted clients such
	// as claude.ai and ChatGPT reach the server from a few shared addresses,
	// so the limit must cover many users connecting at once, while a script
	// filling the Store is held to 20 records a minute per address. An IPv6
	// address counts as its /64, since one host usually has a whole /64 to
	// rotate through. A negative value turns the limit off.
	RegistrationLimit int
	// ClientIP returns the address a registration is counted against. It has
	// the shape of Echo's IPExtractor, so an application passes the extractor
	// it already has. When nil, Mount uses the IPExtractor of the Echo
	// instance if one is set, read at each request so it may be set after
	// Mount, and otherwise, as Handler always does, the host of the request's
	// RemoteAddr (all of it when it cannot be split). Behind a proxy or load
	// balancer without an extractor, every client has the proxy's address
	// and so shares one count, which caps registrations for everyone at
	// RegistrationLimit and lets one client use it up.
	ClientIP func(*http.Request) string
	// 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
	// DisableClientMetadataDocuments turns Client ID Metadata Documents off:
	// the metadata advertises client_id_metadata_document_supported false,
	// and a client_id that is an https URL is an unknown client, unless it is
	// listed in Clients, so the server never fetches a URL. Clients register
	// dynamically instead. A client connected through a document before the
	// switch can no longer refresh (invalid_client); its access tokens stay
	// valid until they expire. The zero value keeps documents on.
	DisableClientMetadataDocuments bool
}

type Grant struct {
	// Subject identifies the user, for example an account id. Required: an
	// empty Subject fails the login with an internal error.
	Subject string `json:"subject"`
	// Scope is the granted scope string, space separated, exactly as the
	// application returned it from Verify or passed it to Approve, empty when
	// it granted none. The scope the client requested is never copied in; it
	// only echoes in the token response.
	Scope string `json:"scope,omitempty"`
}

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, with Subject set and Scope as granted, empty for none.
	// 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
	// Scope is the raw space-separated scope the client requested, so the
	// login page can grant, narrow or refuse it in the Grant.Scope it passes
	// to Approve. It is never granted on its own.
	Scope 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 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)
	// Swap replaces the live value under kind and id with value, until
	// expiresAt, only when the stored value equals old, byte for byte: old
	// is always a value Get returned, never re-encoded, so a store that
	// normalises its values must compare the same way. It returns an error
	// with code ez.ENOTFOUND when the record is absent, expired or holds a
	// different value, so the caller re-reads and decides again.
	Swap(ctx context.Context, kind, id string, old, value []byte, expiresAt time.Time) error
	// Delete removes the value. A missing value is not an error.
	Delete(ctx context.Context, kind, id string) error
}