appauth

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

type Config struct {
	// Issuer is SystemAuth's issuer URL.
	Issuer string
	// ClientID is the application's OAuth client at SystemAuth.
	ClientID string
	// ClientSecret is the confidential client's secret. Empty for a public
	// client.
	ClientSecret string
	// PublicURL is the origin the application is reached at, such as
	// https://app.example.com. The redirect URL and the DPoP proof URL are
	// built from it.
	PublicURL string
	// AllowedOrigins are other origins that may call the BFF and be
	// post-login return targets.
	AllowedOrigins []string
	// AccessTokenAudience, when set, must be in the aud of access tokens
	// the application's API accepts.
	AccessTokenAudience string
	// AcceptedClientIDs are other OAuth clients whose access tokens the API
	// accepts, such as a command-line tool's. ClientID is always accepted.
	AcceptedClientIDs []string
	// Scopes are requested at sign-in in addition to
	// relyingparty.DefaultScopes.
	Scopes []string
	// DPoPKey is the PEM P-256 private key the application proves
	// possession of to SystemAuth. Sessions' tokens are bound to it, so it
	// must survive restarts and be shared by every instance.
	DPoPKey string
	// DPoPKeyFile is a file holding DPoPKey, for deployments that deliver
	// secrets as files. Set one of DPoPKey and DPoPKeyFile.
	DPoPKeyFile string
	// BasePath is where the BFF is mounted. Default: DefaultBasePath.
	BasePath string
}

type Labels struct {
	Issuer, ClientID, PublicURL, AllowedOrigins, AccessTokenAudience,
	AcceptedClientIDs, DPoPKey, DPoPKeyFile string
}

type Options struct {
	// Principals is the application's principal store (required).
	Principals relyingparty.PrincipalStore
	// Sessions stores browser sessions, and LoginStates in-flight sign-ins.
	// Both are required unless PublicURL is a loopback host, where the
	// in-memory stores are used and sessions end at a restart. Use
	// pgstore.NewStores in production.
	Sessions    relyingparty.SessionStore
	LoginStates relyingparty.LoginStateStore

	// Application is the application's key in an organization's
	// applications (the orgs claim's apps). When set, the default
	// membership source keeps only organizations where the principal holds
	// a role of it that KnownRole accepts (any role when KnownRole is nil).
	Application string
	KnownRole   func(role string) bool
	// Memberships replaces the default membership source, the orgs claim
	// with SystemAuth's memberships endpoint as fallback. It is used as is:
	// Application does not filter it. Pass relyingparty.LocalMemberships for
	// an application that keeps its own membership tables.
	Memberships relyingparty.MembershipSource

	// Apps lists the deployment's application catalog in the browser
	// session, for the product switcher.
	Apps appcatalog.Source
	// Metadata is SystemAuth's provider metadata, when the host already has
	// it (an embedded SystemAuth). Without it, New discovers it.
	Metadata *relyingparty.Metadata
	// HTTPClient makes the calls to SystemAuth. Default: http.DefaultClient.
	HTTPClient *http.Client
	// Revocation, when set, applies recorded access changes to sessions and
	// tokens at once (ADR-010).
	Revocation *relyingparty.RevocationCache
	// LoginErrorPath, when set, is the app's sign-in page: a browser whose
	// sign-in fails is redirected there with ?error=<CODE> instead of shown
	// a JSON error. See relyingparty.BFFConfig.LoginErrorPath.
	LoginErrorPath string
	// ReplayCache rejects reused DPoP proofs. Default: in memory, per
	// instance; instances that share an API need a shared cache. Unless
	// the public URL is a loopback host or SingleInstance is set, New
	// logs a warning when it uses the default.
	ReplayCache relyingparty.DPoPReplayCache
	// SingleInstance declares that one instance serves the API, so the
	// default in-memory replay cache sees every proof.
	SingleInstance bool
	// Authenticators are tried after the session and token, for requests
	// they do not recognize, such as AAuth-signed agent requests.
	Authenticators []requestprincipal.Authenticator

	// ServiceAccounts accepts SystemAuth service accounts' tokens: their
	// client (relyingparty.ServiceAccountClientID) is accepted, and an
	// account's local principal is created on its first request
	// (relyingparty.BearerConfig.ServicePrincipals). Principals must support
	// service identities, as pgstore.PrincipalStore does.
	ServiceAccounts bool

	// EphemeralDPoPKey lets the application start without a DPoP key: one
	// is generated per process, so people sign in again after every
	// restart. For local development only.
	EphemeralDPoPKey bool
	// AllowBearerTokens also accepts unbound access tokens with the Bearer
	// scheme, from clients SystemAuth exempts from DPoP.
	AllowBearerTokens bool

	// ResourceName names the application in its protected resource
	// metadata (RFC 9728).
	ResourceName string
	// Labels name the settings in New's configuration errors. Default:
	// DefaultLabels.
	Labels *Labels
	// Logger receives warnings and operational errors. Default:
	// slog.Default().
	Logger *slog.Logger

	// ClientAddress finds the client address behind the application's
	// reverse proxies (see clientaddr), for the application's rate limits
	// (ClientAddress returns it). Default: the direct peer.
	ClientAddress *clientaddr.Resolver
	// SignedInRateLimit, when set, limits each signed-in principal or
	// service account after Middleware authenticates it, such as
	// ratelimit.NewSignedInLimiter. Anonymous requests are not limited by
	// it.
	SignedInRateLimit *ratelimit.Limiter
}

type ResourceMetadata struct {
	// Resource is the application's resource identifier, its public URL.
	Resource string `json:"resource"`
	// AuthorizationServers are the issuers whose tokens are accepted.
	AuthorizationServers []string `json:"authorization_servers"`
	// BearerMethodsSupported is how tokens are presented.
	BearerMethodsSupported []string `json:"bearer_methods_supported"`
	// DPoPSigningAlgValuesSupported are the proof algorithms accepted.
	DPoPSigningAlgValuesSupported []string `json:"dpop_signing_alg_values_supported"`
	// DPoPBoundAccessTokensRequired is true unless unbound tokens are
	// accepted.
	DPoPBoundAccessTokensRequired bool `json:"dpop_bound_access_tokens_required"`
	// ResourceName is Options.ResourceName, for display.
	ResourceName string `json:"resource_name,omitempty"`
}