middleware

type AuthMode string

type AuthOptions struct {
	Mode              string
	BearerTokenEnv    string
	EdgeSecretEnv     string
	BearerRole        string
	AllowPublicPaths  []string // exact path matches that skip auth entirely (e.g. /healthz)
	AllowPublicRoutes []PublicRoute
	// HTMLUnauthorizedPaths/Routes keep browser-facing admin UI failures out
	// of the JSON API envelope while still requiring normal credentials.
	HTMLUnauthorizedPaths  []string
	HTMLUnauthorizedRoutes []PublicRoute
	// Dynamic providers are evaluated for every request. They let first-run
	// setup generate a token without rebuilding the middleware chain.
	ModeProvider              func() string
	BearerTokenProvider       func() string
	EdgeSecretProvider        func() string
	BearerRoleProvider        func() string
	AdminUsernameProvider     func() string
	AdminPasswordHashProvider func() string
	// SmokeTokenProvider returns the optional public demo token used by the
	// smoke UI on `/`. When non-empty and matching the presented Bearer,
	// the middleware attaches a Source="smoke", Plan="demo" identity so
	// handlers and the rate-limiter can treat demo traffic accordingly.
	SmokeTokenProvider func() string
	// Bootstrap routes are public only while BootstrapAllowed returns true.
	// The server uses this for the first settings write when bearer auth is
	// configured but no bearer token exists yet.
	AllowBootstrapPaths  []string
	AllowBootstrapRoutes []PublicRoute
	BootstrapAllowed     func(*http.Request) bool
	// RequireAuthenticatedMode is defence-in-depth on top of
	// config.ValidateServerProductionAuth. When true, the AuthModeNone
	// branch of verify() refuses to issue the anonymous Identity even if
	// the resolved mode is "none" or empty. Bootstrap sets this for
	// non-loopback binds so a future code path that skips startup
	// validation cannot accidentally serve unauthenticated traffic to the
	// public internet. Admin-session and smoke-token fallbacks remain
	// available — only the implicit anonymous identity is suppressed.
	RequireAuthenticatedMode bool
}

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

type Identity struct {
	UserID string `json:"user_id"`
	OrgID  string `json:"org_id"`
	Plan   string `json:"plan"`
	Role   string `json:"role,omitempty"` // "admin" | "" (default)
	Source string `json:"source"`         // "none" | "bearer" | "edge_hmac" | "basic" | "admin_session"
}

type Middleware func(http.Handler) http.Handler

type PublicRoute struct {
	Path       string
	PathPrefix string
	PathSuffix string
	Methods    []string
}

type RateLimitOptions struct {
	RequestsPerSecond float64 // sustained rate; zero disables limiting
	Burst             int     // max tokens in bucket; zero disables limiting
	// AllowPublicPaths is the list of exact request paths that bypass the
	// limiter entirely. Production deployments must always include
	// `/healthz` and `/readyz` so external probes (Render, Kubernetes) are
	// never rate-limited away from a real outage.
	AllowPublicPaths []string
	// MaxBuckets caps the in-memory bucket map. Zero falls back to
	// defaultRateLimitMaxBuckets. Once the cap is hit, the least-recently-
	// used bucket is evicted before a new one is inserted.
	MaxBuckets int
	// SweepInterval controls how often a background goroutine scans the
	// bucket map and evicts entries whose last access is older than
	// SweepMaxAge. Zero falls back to 5 minutes; set negative to disable.
	SweepInterval time.Duration
	// SweepMaxAge is the staleness threshold beyond which buckets are
	// evicted by the background sweeper. Zero falls back to a value
	// derived from Burst/RequestsPerSecond.
	SweepMaxAge time.Duration
	// Context, when non-nil, controls the lifetime of the background
	// sweeper goroutine. Cancellation stops the sweep loop. Production
	// callers should pass the server's shutdown context here.
	Context context.Context //nolint:containedctx // intentional middleware-lifetime ctx
	// EndpointCosts assigns a per-endpoint token cost so expensive
	// handlers (LLM, transcription, session create) drain the bucket
	// faster than cheap ones. Lookup is "METHOD PATH" first (e.g.
	// "POST /v1/dictation/transcribe"), then bare PATH, then default
	// 1.0. Zero or negative entries fall back to 1.0. (Audit S-4)
	EndpointCosts map[string]float64
	// DemoDailyQuota caps how many requests an identity with
	// Plan="demo" (the smoke-token surface) may make per UTC day,
	// keyed by UserID + client IP. Zero disables the quota. Public
	// paths bypass this check the same way they bypass token-bucket
	// rate limiting. (Audit S-5)
	DemoDailyQuota int
	// Now lets tests inject a fake clock for the daily-quota window
	// reset; production leaves it nil and gets time.Now.
	Now func() time.Time
}