public

Documentation

Overview

Package public provides the public-facing HTTP server, assembling routes from the oauth, vault, and wellknown sub-packages.

Index

• func DefaultChain(c ChainDeps, inner http.Handler) http.Handler
• type ChainBuilder
• type ChainDeps
• type Deps
• type Server
  • func NewServer(ctx context.Context, cfg config.ServerConfig, deps Deps, ...) *Server
  • func (s *Server) Handler() http.Handler
  • func (s *Server) Shutdown(ctx context.Context) error
  • func (s *Server) Start() error
• type SessionCookie

Functions

func DefaultChain

func DefaultChain(c ChainDeps, inner http.Handler) http.Handler

DefaultChain is the server's middleware composition:

SecurityHeaders → Recover → RequestID → CORS → Tracing → Metrics → Logging → inner

It is exported so a distribution can build on it instead of restating it; the order, and the invariant that SecurityHeaders and Recover wrap everything else, stay owned here.

Types

type ChainBuilder

type ChainBuilder func(ChainDeps, http.Handler) http.Handler

ChainBuilder composes the server's middleware chain around inner — the routed handler (rate limiter, then mux). It returns the handler NewServer serves.

A nil builder means DefaultChain. A builder is expected to compose AROUND DefaultChain rather than replace it:

deps.BuildChain = func(c public.ChainDeps, inner http.Handler) http.Handler {
	return public.DefaultChain(c, myMiddleware(inner))
}

Composing this way is what keeps a distribution correct over time: middleware it inserts sits INSIDE the chain, so a response it writes without delegating to next still carries CORS and security headers and is recovered, traced, metered and logged. Restating the chain instead of calling DefaultChain would leave the copy to drift silently the next time the chain changes.

Wrapping the RESULT of DefaultChain places middleware above SecurityHeaders and Recover, outside panic safety, and is almost never what a caller wants.

type ChainDeps

type ChainDeps struct {
	// Obs is the observability provider backing Recover/RequestID/Tracing/
	// Metrics/Logging.
	Obs *observability.Provider

	// Secure reports whether HTTPS is enforced, which gates the HSTS header.
	Secure bool

	// CORS is the per-request CORS middleware, already bound to the server's
	// CORSConfigProvider.
	CORS func(http.Handler) http.Handler
}

ChainDeps are the inputs NewServer resolves for the middleware chain and hands to the ChainBuilder.

It exists so the chain can grow new inputs without breaking a distribution's builder: a new middleware that needs a new dependency adds a field here and is consumed inside DefaultChain, leaving every ChainBuilder signature untouched.

type Deps

type Deps struct {
	JWKS wellknown.JWKSProvider
	// ASMetadata assembles the AS discovery document (RFC 8414). Required for
	// the oauth-authorization-server / openid-configuration routes; built in
	// cmd from the static providers (api/ may not import services/adapters).
	ASMetadata        input.ASMetadataPort
	DCR               oauth.DCRProvider
	Auth              oauth.UserAuthProvider
	Authorize         oauth.AuthorizeProvider
	Consent           oauth.ConsentProvider
	Token             oauth.TokenProvider
	ClientCredentials oauth.ClientCredentialsProvider
	TokenExchange     oauth.TokenExchangeProvider
	JWTBearer         oauth.JWTBearerProvider
	Revoke            oauth.RevocationProvider
	Introspect        oauth.IntrospectionProvider
	// OAuthConfig gates POST /oauth/introspect at runtime (IntrospectionEnabled)
	// from the same source as the discovery document. Optional.
	OAuthConfig output.OAuthConfigProvider
	Health      wellknown.HealthChecker
	OIDC        oauth.OIDCFlowProvider
	// LoginDisplay supplies the login page's presentation fields (OIDC
	// button label + show-local-login) per request. It is required when the
	// login routes are registered: RegisterLoginRoutes panics if it is nil —
	// there is no silent fallback. It carries only presentation data, never
	// the upstream client secret.
	LoginDisplay output.LoginDisplayProvider
	// URLs constructs URLs for internal authserver routes (the OIDC start
	// link, the post-login redirect destination) and resolves the mount path
	// prefix + cookie scope (PathPrefix, CookiePath). REQUIRED: NewServer
	// panics if nil — there is no silent fallback. The OSS default,
	// static.NewURLBuilder(), serves at the root (empty prefix, "/" cookie
	// path, byte-identical to the pre-port behavior); an alternative builder
	// may scope URLs/cookies under a mount path.
	URLs output.URLBuilder
	// StateCodec encodes/decodes the OAuth state parameter for the OIDC
	// federation flow. Required when OIDC is non-nil; nil panics at
	// route registration time. Default impl: static.NewStateCodec.
	StateCodec output.StateCodec
	// SessionSecretProvider supplies the HMAC secret for session cookies / CSRF
	// tokens per request. REQUIRED: NewServer panics if it is nil — there is no
	// silent fallback. cmd/authserver/serve.go wires the OSS default
	// static.NewSessionSecretProvider over the secret it resolves from
	// cfg.Session.Secret (or a random ephemeral secret when that is unset). An
	// alternative provider can source the secret per deployment (KMS / HSM /
	// env-keyed rotation).
	SessionSecretProvider output.SessionSecretProvider
	// SessionConfigProvider supplies the session-cookie policy
	// (MaxAge/Secure/SameSite/FailClosed) per request. REQUIRED: NewServer
	// panics if nil. cmd/authserver/serve.go wires the OSS default
	// static.NewSessionConfigProvider over cfg.Session, byte-identical to the
	// pre-seam server. An alternative provider may resolve policy per request.
	SessionConfigProvider output.SessionConfigProvider
	// OIDCStateConfigProvider resolves the OIDC state-cookie TTL per request.
	// REQUIRED when OIDC routes register. Default: static.NewOIDCStateConfigProvider.
	OIDCStateConfigProvider output.OIDCStateConfigProvider
	// SessionCookie carries the only two boot-time session-cookie attributes the
	// server reads directly. The cookie *policy* (MaxAge/SameSite/FailClosed)
	// comes from SessionConfigProvider and the signing secret from
	// SessionSecretProvider — neither is settable here, so a misconfiguration
	// can't hide in an ignored field.
	SessionCookie SessionCookie
	RateLimitCfg  config.RateLimitConfig
	Connect       connectionapi.ConnectProvider
	// IssuerProvider resolves the AS issuer URL — the public base for
	// everything under the host. The OAuth sub-package builds both
	// consent_required URL flavors from it: the broker upstream re-connect
	// URL (/connect/<provider>) and the AS-side re-consent URL
	// (/authorize?resource=…, token-exchange and bound-B/bound-C flows).
	// In the OSS deployment this is the static cfg.Server.Issuer.
	IssuerProvider output.IssuerProvider

	// CORSConfigProvider resolves the CORS allowed-origins allowlist per
	// request for the browser-facing endpoints (token, introspection,
	// revocation, registration, discovery). REQUIRED: NewServer panics if it is
	// nil — there is no silent fallback. cmd/authserver/serve.go wires the OSS
	// default static.NewCORSConfigProvider(cfg.Server.AllowedOrigins), which
	// returns the boot allowlist on every call (byte-identical to the pre-seam
	// server). A resolution failure fails closed: no CORS headers for that
	// request, never a fallback to a stale or process-wide list. An alternative
	// provider may source the allowlist per request.
	CORSConfigProvider output.CORSConfigProvider

	// BuildChain composes the middleware chain around the routed handler. Nil —
	// the default — builds DefaultChain, byte-for-byte the chain this server has
	// always served. A distribution supplies a builder to insert middleware
	// inside the chain, and is expected to compose around DefaultChain rather
	// than restate it (see ChainBuilder).
	//
	// The builder supplies handlers; it does not own the order. SecurityHeaders
	// and Recover wrap everything DefaultChain composes, including anything the
	// builder injects.
	BuildChain ChainBuilder

	// DPoP (RFC 9449) — optional.
	DPoPNonce oauth.DPoPNonceIssuer // non-nil when DPoP is enabled
	DPoPCfg   config.DPoPConfig     // DPoP configuration

	// Users is consulted by SessionMiddleware to reject session cookies naming a
	// user who no longer exists OR is no longer active. Pass the same UserStore
	// the rest of the app uses — production wraps it in storage.WithUserCache
	// so this lookup does not become a DB query per request. When nil, the
	// middleware accepts any cookie that passes HMAC + expiry validation. Some
	// tests rely on that; production must not, since /authorize and /consent
	// have no user check of their own, so this is what makes a disable take
	// effect on the front channel. See SessionMiddleware.SetUserStore.
	Users output.UserStore

	// Audit records the auth-failure lockout event. Optional: nil disables
	// recording and changes nothing about the lockout itself.
	Audit oauth.AuditRecorder
}

Deps holds the dependencies injected into the public HTTP server.

type Server

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

Server is the public-facing HTTP server.

func NewServer

func NewServer(ctx context.Context, cfg config.ServerConfig, deps Deps, obs *observability.Provider) *Server

NewServer creates the public HTTP server with routes wired.

func (*Server) Handler

func (s *Server) Handler() http.Handler

Handler returns the server's HTTP handler for testing.

func (*Server) Shutdown

func (s *Server) Shutdown(ctx context.Context) error

Shutdown gracefully drains in-flight requests.

func (*Server) Start

func (s *Server) Start() error

Start begins listening. It blocks until the server stops.

type SessionCookie

type SessionCookie struct {
	Name   string
	Secure bool
}

SessionCookie carries the boot-time session-cookie attributes the server reads directly: the cookie Name (default "authserver_session" when empty) and the deployment's Secure/HTTPS posture (drives HSTS and the Secure floor that an alternative SessionConfigProvider may only tighten above, never downgrade).