authhttp

type ActionAvailability = authkit.ActionAvailability

type AuthCapabilities struct {
	Registration AuthRegistrationCapabilities `json:"registration"`
	Providers    []AuthProviderSummary        `json:"providers"`
	Password     AuthPasswordCapabilities     `json:"password"`
	Passwordless AuthPasswordlessCapabilities `json:"passwordless"`
	Passkeys     AuthPasskeyCapabilities      `json:"passkeys"`
	Solana       AuthSolanaCapabilities       `json:"solana"`
	Verification AuthVerificationCapabilities `json:"verification"`
	Languages    []string                     `json:"languages,omitempty"`
}

type AuthPasskeyCapabilities struct {
	Login bool `json:"login"`
}

type AuthPasswordCapabilities struct {
	Login bool `json:"login"`
}

type AuthPasswordlessCapabilities struct {
	Enabled  bool     `json:"enabled"`
	Channels []string `json:"channels,omitempty"`
}

type AuthProviderSummary struct {
	ID                   string `json:"id"`
	Name                 string `json:"name"`
	SupportsLogin        bool   `json:"supports_login"`
	SupportsRegistration bool   `json:"supports_registration"`
	SupportsLink         bool   `json:"supports_link"`
}

type AuthRegistrationCapabilities struct {
	Mode                string `json:"mode"`
	InviteTokenRequired bool   `json:"invite_token_required"`
}

type AuthSolanaCapabilities struct {
	Login bool `json:"login"`
}

type AuthVerificationCapabilities struct {
	Registration string `json:"registration"`
}

type ClientIPFunc func(r *http.Request) string

type Config struct {
	// Redis overrides the engine's Redis client for the HTTP layer's OIDC/SIWS
	// state caches and rate limiter. Nil reuses embedded.Deps.Redis (#210), so
	// most hosts never set it.
	Redis *redis.Client

	// RateLimits overlays bucket-specific limits onto DefaultRateLimits (#242).
	RateLimits map[string]ratelimit.Limit
	// Limiter replaces AuthKit's automatic limiter. ADVANCED: normal
	// deployments let AuthKit own the policy (Redis-backed when Redis is wired,
	// in-memory otherwise). RateLimits are not applied to a custom limiter.
	Limiter RateLimiter
	// DisableRateLimiting turns rate limiting off. TESTS ONLY: it removes the
	// brute-force and spam protection.
	DisableRateLimiting bool

	// Client-IP posture (ak#299). Exactly what sits in front of AuthKit must be
	// declared — behind an undeclared proxy every client shares the proxy's one
	// per-IP rate-limit bucket. One of the four is required.
	//
	// TrustedProxies are the CIDRs of reverse proxies / load balancers whose
	// X-Forwarded-For is honoured (walked right-to-left past our own hops).
	// CF-Connecting-IP is never trusted from these peers.
	TrustedProxies []string
	// CloudflareProxies are Cloudflare's published egress ranges: X-Forwarded-For
	// like a trusted proxy plus CF-Connecting-IP when that header is absent.
	// Set it ONLY where Cloudflare fronts the origin, and lock the origin down
	// to Cloudflare ingress.
	CloudflareProxies []string
	// DirectPeerIP asserts nothing sits in front: RemoteAddr IS the end client.
	DirectPeerIP bool
	// ClientIP is a bespoke extraction strategy. ADVANCED: it replaces the
	// proxy handling above entirely.
	ClientIP ClientIPFunc

	// Languages declares the supported UI languages; the zero value is
	// English-only.
	Languages LanguageConfig

	// Documents are the published-document providers (normally
	// *documents.Service values) served at the RouteDocuments mount and
	// stamped by the delegated-token mint route (#260/#261). Requires
	// embedded.Config.Documents.Readers.
	Documents []DocumentProvider
	// contains filtered or unexported fields
}

type DocumentProvider interface {
	// Reference is the process snapshot reference stamped into minted tokens.
	Reference() documents.Reference
	// Lookup serves any persisted digest for the publication route.
	Lookup(ctx context.Context, digest string) (documents.SignedDocument, error)
	// CurrentDigest re-validates (and repairs) the persisted snapshot artifact.
	CurrentDigest(ctx context.Context) (string, error)
	// EnsureSigningKID re-signs the artifact when it is not signed by the key
	// that just minted a token referencing it.
	EnsureSigningKID(ctx context.Context, tokenKID string) error
}

type LanguageConfig struct {
	Supported []string
	Default   string
}

type MountOptions struct {
	// Groups selects the mounted route groups. Nil mounts the default API
	// surface plus browser OIDC. Non-nil mounts exactly the named groups —
	// include RouteBrowserOIDC to keep the browser redirect flows.
	Groups []RouteGroup
	// APIPrefix anchors the JSON API routes. "" means DefaultAPIPrefix; "/"
	// mounts the API at root.
	APIPrefix string
	// ExcludeRoutes drops routes the host shadows with its own handlers.
	// Matched by method + prefix-neutral RouteSpec path. Exclusion does NOT
	// alter the verifier's MFA-enrollment exempt-path set — that is derived
	// from the full route registry at authhttp.New time, so a shadowed enroll
	// route stays reachable through the host's replacement.
	ExcludeRoutes []RouteRef
	// Wrap decorates every RouteSpec-backed handler (API + browser OIDC) at
	// mount time. JWKS is not wrapped (it carries no RouteSpec).
	Wrap func(RouteSpec, http.Handler) http.Handler
	// RefreshCookie (ak#271) delivers the rotating refresh token as an
	// HttpOnly+Secure+SameSite=Lax cookie (RefreshCookieName) instead of a JSON
	// body field, so an injected script cannot read the durable credential.
	// OFF by default: a host that leaves this false gets byte-identical
	// behaviour, refresh_token in every body as before.
	//
	// When on, every session-establishing response sets the cookie and omits
	// refresh_token from its body/fragment/postMessage payload; POST /token
	// accepts the cookie when the body carries no token (body still wins, so a
	// mid-migration client is never stranded); and DELETE /logout clears it.
	// The cookie is Path-scoped to this mount's POST /token — the only route
	// that reads a refresh token — so it never rides the SPA document or assets.
	//
	// Browser-facing by construction: the host must serve the SPA and this
	// mount on the SAME origin, or the cookie never reaches the refresh call.
	RefreshCookie bool
}

type RateLimitResult struct {
	Allowed      bool
	RetryAfter   time.Duration
	Availability *ActionAvailability
}

type RateLimiter interface {
	AllowNamed(bucket string, key string) (bool, error)
}

type RateLimiterWithResult interface {
	AllowNamedResult(bucket string, key string) (ratelimit.Result, error)
}

type RouteAuthTier string

type RouteGroup string

type RouteRef struct {
	Method string
	Path   string
}

type RouteSpec struct {
	Method  string
	Path    string
	Group   RouteGroup
	Handler http.Handler
	// Auth is the tier the handler wrapper enforces before the handler runs;
	// Permission names the root/group permission for AuthPermission (#328).
	Auth       RouteAuthTier
	Permission authkit.Perm
	// Bucket is the per-IP rate-limit bucket APIRoutes applies in front of the
	// handler ("" = none). Per-identifier and branch-specific buckets stay in
	// the handler.
	Bucket string
	// MFAEnrollmentExempt marks a route as part of the 2FA enroll/challenge/
	// verify surface a forced-enrollment-gated user (verify.WithRequireMFAEnrollment)
	// must still be able to reach. authhttp.New derives the verifier's exempt-path
	// allowlist from routes tagged here (#243) — the route table is the single
	// source of truth, so a rename/add stays consistent by construction.
	MFAEnrollmentExempt bool
}

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