csrf

type Config struct {
	CookieName   string
	HeaderName   string
	FormField    string
	CookiePath   string
	CookieDomain string
	CookieSecure bool

	// AllowInsecureCookie is required to disable Secure on CSRF cookies. This
	// explicit opt-out prevents a partial Config literal from silently weakening
	// the secure default. Intended for loopback/local development only.
	AllowInsecureCookie bool

	CookieSameSite fh.SameSite

	// CookieMaxAge controls both CSRF cookies. Zero creates session cookies.
	// A session cookie is the default so CSRF lifetime does not accidentally
	// outlive or conflict with an application's authentication lifetime.
	CookieMaxAge time.Duration

	// BindingCookieName names the HttpOnly random browser-session binding cookie.
	// It is included in the CSRF-token MAC and prevents cookie-injection/fixation
	// attacks against a naive double-submit construction.
	BindingCookieName string

	// DisableBrowserBinding explicitly disables the HttpOnly browser-binding
	// cookie. This weakens the default and should normally be used only when a
	// strong SessionBinding is always available.
	DisableBrowserBinding bool

	// Secret is a convenient single active key. For key rotation, prefer Keys.
	// If both Secret and Keys are configured, configuration is rejected.
	Secret []byte

	// Keys enables signing-key rotation. The first key signs; every key verifies.
	Keys []Key

	// SessionBinding optionally binds tokens to the application's auth/session
	// identity in addition to the default browser-session binding cookie.
	SessionBinding SessionBinding

	// TrustedOrigins are exact additional origins allowed to submit unsafe
	// requests, e.g. "https://app.example.com". Wildcards are intentionally not
	// supported.
	TrustedOrigins []string

	// TargetOrigin pins the browser-visible target origin. It is strongly
	// recommended behind TLS-terminating reverse proxies/load balancers.
	TargetOrigin string

	// TargetOriginResolver is the dynamic equivalent of TargetOrigin. Configure
	// at most one of TargetOrigin and TargetOriginResolver.
	TargetOriginResolver TargetOriginResolver

	// RequireOriginHeader is retained for source compatibility. The secure
	// default is true. Because bool zero-values cannot express an explicit false
	// in a partial Config, use AllowMissingOrigin to opt out.
	RequireOriginHeader bool

	// AllowMissingOrigin permits unsafe requests carrying neither Origin nor
	// Referer. Prefer bypassing CSRF on authenticated non-browser routes instead.
	AllowMissingOrigin bool

	// AllowUntrustedOrigin disables Origin/Referer and Fetch Metadata enforcement
	// while retaining token verification. Intended only for local development.
	AllowUntrustedOrigin bool

	// CheckFetchMetadata is retained as an enable switch. It is enabled by
	// default. Use DisableFetchMetadata for an explicit opt-out.
	CheckFetchMetadata bool

	// DisableFetchMetadata explicitly disables Sec-Fetch-Site validation.
	DisableFetchMetadata bool

	// ProtectWebSockets enables strict Origin/Fetch-Metadata checks for WebSocket
	// handshakes even though HTTP GET is normally a safe method. Enabled by
	// default. Browser WebSocket APIs cannot reliably attach the CSRF header, so
	// WebSocket protection is origin-based rather than token-header-based.
	ProtectWebSockets bool

	// AllowUnprotectedWebSockets explicitly disables the secure WebSocket default.
	AllowUnprotectedWebSockets bool

	// AutoRotateOnChange automatically re-issues the CSRF token when the
	// session binding changes (for example after login, logout, or account
	// switching). When true, the middleware detects binding changes by
	// comparing a short HMAC fingerprint stored in a companion cookie and
	// calls RotateToken transparently. This closes the gap where a
	// pre-authentication CSRF token could remain valid after the session
	// identity changes.
	AutoRotateOnChange bool

	// Extractor overrides HeaderName/FormField extraction when non-nil.
	Extractor TokenExtractor

	// Next bypasses this middleware for selected routes. Prefer this for
	// authenticated machine-to-machine/non-browser APIs instead of weakening
	// global origin policy.
	Next func(fh.Ctx) bool
}

type Key struct {
	ID     string
	Secret []byte
}

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

type SessionBinding func(fh.Ctx) ([]byte, error)

type TargetOriginResolver func(fh.Ctx) (string, error)

type TokenExtractor func(fh.Ctx) (string, error)