middleware

type CORSConfig struct {
	// AllowedOrigins lists exact origins ("https://app.example.com") or "*".
	AllowedOrigins []string
	// AllowedMethods defaults to GET, HEAD, POST, PUT, PATCH, DELETE.
	AllowedMethods []string
	// AllowedHeaders defaults to Accept, Authorization, Content-Type,
	// X-Requested-With, X-CSRF-Token.
	AllowedHeaders []string
	// ExposedHeaders are readable by the browser.
	ExposedHeaders []string
	// AllowCredentials allows cookies/Authorization; incompatible with "*".
	AllowCredentials bool
	// MaxAge caches preflight responses.
	MaxAge time.Duration
}

type LoggerOptions struct {
	// TruncateIP logs the /24 network of IPv4 addresses and the /48 of
	// IPv6 ones in peer and ip (203.0.113.0, 2001:db8:1234::) instead of
	// the address, for data-minimising logs (LOG_TRUNCATE_IP). Rate limits
	// and c.IP() keep the full address.
	TruncateIP bool
}

type MaintenanceConfig struct {
	// File is the state file (default DefaultMaintenanceFile).
	File string
	// Key signs bypass cookies (derive it from APP_KEY). Without a key the
	// secret bypass is disabled: an unkeyed HMAC would be forgeable.
	Key []byte
	// PreviousKeys still accept bypass cookies signed before an APP_KEY
	// rotation (derive them from APP_PREVIOUS_KEYS); such a cookie is
	// re-issued under Key.
	PreviousKeys [][]byte
	// Except lists paths always served (default "/up").
	Except []string
	// Secure marks the bypass cookie Secure (production, HTTPS).
	Secure bool
}

type MaintenanceState struct {
	// Secret, when set, lets visitors of /<secret> through (stored hashed).
	Secret string `json:"-"`
	// Retry is sent as Retry-After.
	Retry time.Duration `json:"-"`

	SecretHash string    `json:"secret_hash,omitempty"`
	RetryAfter int       `json:"retry_after,omitempty"`
	Since      time.Time `json:"since"`
}

type Middleware = func(http.Handler) http.Handler

type SecureHeadersConfig struct {
	// CSP is the Content-Security-Policy; "{nonce}" is replaced with a
	// per-request nonce. Empty uses DefaultCSP; "-" disables the header.
	CSP string
	// HSTSMaxAge enables Strict-Transport-Security on HTTPS requests.
	// Zero uses two years; negative disables it.
	HSTSMaxAge time.Duration
	// HSTSForce sends Strict-Transport-Security on every response that
	// reaches SecureHeaders, also on requests that look like plain HTTP
	// (middleware installed before it, such as Maintenance's 503, answers
	// without it). Use it only when every public
	// request reaches a TLS-terminating proxy whose range cannot be
	// trusted (so TrustForwardedProto cannot be used): it asserts the
	// public origin is HTTPS-only instead of checking each request.
	// Browsers ignore HSTS received over plain HTTP (RFC 6797 section 8.1).
	HSTSForce bool
	// FrameOptions defaults to DENY; "-" disables it.
	FrameOptions string
	// ReferrerPolicy defaults to strict-origin-when-cross-origin.
	ReferrerPolicy string
	// PermissionsPolicy defaults to camera=(), microphone=(), geolocation=().
	PermissionsPolicy string
	// TrustForwardedProto treats X-Forwarded-Proto: https as HTTPS (set it
	// only behind a trusted proxy).
	TrustForwardedProto bool
	// TrustedProxies, when non-empty, limits TrustForwardedProto to
	// requests whose direct peer is in one of these networks, so clients
	// that reach the app around the proxy cannot claim HTTPS.
	TrustedProxies []*net.IPNet
	// DevServer returns the origin of a running asset dev server (the Vite
	// hot URL) or "". When set, the origin is allowed in script-src,
	// style-src, img-src, font-src and connect-src (plus its ws:// form for
	// hot reload). Wire it only outside production.
	DevServer func() string
	// CSPSources adds sources to directives of the policy, e.g. an
	// analytics origin in script-src and connect-src, or the 'sha256-...'
	// hash of a style a library injects. A "-src" directive missing from
	// the policy starts from the default-src sources. Unsafe sources
	// ('unsafe-*' keywords, "*", nonces, scheme-only sources in script
	// directives) are refused: write a full CSP to opt into them.
	CSPSources map[string][]string
	// ReportURI receives CSP violation reports: an absolute https URL or
	// a path (plain http is refused at boot). It adds report-uri and report-to directives and a
	// Reporting-Endpoints header naming the "csp-endpoint" group.
	ReportURI string
}

type StaticConfig struct {
	// Prefix is the URL prefix ("/" serves files at the root).
	Prefix string
	// ImmutablePrefixes get a one-year immutable cache (hashed build output).
	// Elsewhere only fingerprinted names (see Static) are immutable.
	ImmutablePrefixes []string
}