engine.go

// Package authsome provides a composable authentication engine for the Forge ecosystem.
//
// AuthSome v0.5.0 is an interface-driven, store-abstracted authentication engine
// with a type-cached plugin registry, global hook bus, strategy-based authentication,
// and optional bridges to forgery extensions (Chronicle, Warden, Keysmith, Relay).
package authsome

import (
	"context"
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"errors"
	"fmt"
	"os"
	"slices"
	"strings"
	"sync"
	"sync/atomic"
	"testing"
	"time"

	log "github.com/xraph/go-utils/log"

	"github.com/xraph/forge"
	"github.com/xraph/forge/extensions/auth"

	"github.com/xraph/authsome/account"
	"github.com/xraph/authsome/apikey"
	"github.com/xraph/authsome/app"
	"github.com/xraph/authsome/appclientconfig"
	"github.com/xraph/authsome/appsessionconfig"
	"github.com/xraph/authsome/authprovider"
	"github.com/xraph/authsome/authz"
	"github.com/xraph/authsome/bridge"
	"github.com/xraph/authsome/bridge/ledgeradapter"
	"github.com/xraph/authsome/ceremony"
	"github.com/xraph/authsome/dpop"
	"github.com/xraph/authsome/formconfig"
	"github.com/xraph/authsome/hook"
	"github.com/xraph/authsome/id"
	"github.com/xraph/authsome/internal/telemetry"
	"github.com/xraph/authsome/lockout"
	"github.com/xraph/authsome/middleware"
	"github.com/xraph/authsome/organization"
	"github.com/xraph/authsome/plugin"
	"github.com/xraph/authsome/principal"
	"github.com/xraph/authsome/ratelimit"
	"github.com/xraph/authsome/rbac"
	"github.com/xraph/authsome/session"
	"github.com/xraph/authsome/settings"
	"github.com/xraph/authsome/store"
	"github.com/xraph/authsome/strategy"
	"github.com/xraph/authsome/tokenformat"
	"github.com/xraph/authsome/user"

	"github.com/xraph/grove"
	"github.com/xraph/keysmith"
	xledger "github.com/xraph/ledger"
	ledgerstore "github.com/xraph/ledger/store"
	"github.com/xraph/warden"
	wardenid "github.com/xraph/warden/id"
	"github.com/xraph/warden/resourcetype"
)

// Engine is the core AuthSome orchestrator. It holds only interfaces —
// no concrete implementations — for maximum pluggability.
type Engine struct {
	config Config
	store  store.Store
	logger log.Logger

	// retentionStop ends the retention sweeper; retentionDone closes once
	// it has. Both are nil while no sweeper runs.
	retentionStop chan struct{}
	retentionDone chan struct{}

	// Plugin system
	plugins            *plugin.Registry
	hooks              *hook.Bus
	strategies         *strategy.Registry
	pendingPlugins     []plugin.Plugin
	pendingStrategies  []pendingStrategy
	pendingAppSessCfgs []*appsessionconfig.Config

	// principalAuthGate scores machine callers (API keys, and any other
	// credential that authenticates without a human sign-in) through the
	// principal-auth hooks before a session is minted. Built once during
	// NewEngine and exposed to plugins via PrincipalAuthGate, which
	// implements plugin.PrincipalAuthGateProvider.
	principalAuthGate *principalAuthGate
	// principalAuthTTL controls how long an allow verdict is cached, keyed
	// on credential and source IP together. Set via WithPrincipalAuthTTL;
	// defaults to five minutes.
	principalAuthTTL time.Duration

	// First-class authorization engine (optional, replaces bridge for RBAC)
	wardenEng *warden.Engine

	// First-class key management engine (optional, replaces bridge for API keys)
	keysmithEng *keysmith.Engine

	// First-class billing engine (optional, provides store access for subscription plugin)
	ledgerEng *xledger.Ledger

	// Optional forgery bridges (injected, not required)
	chronicle    bridge.Chronicle
	authorizer   bridge.Authorizer
	keyManager   bridge.KeyManager
	relay        bridge.EventRelay
	mailer       bridge.Mailer
	sms          bridge.SMSSender
	heraldBridge bridge.Herald
	vault        bridge.Vault
	dispatcher   bridge.Dispatcher
	ledger       bridge.Ledger
	metrics      bridge.MetricsCollector

	// tel holds authsome's own metric families, recorded into the sink
	// WithMetricsSink was given. Nil records nothing.
	tel *telemetry.Metrics

	// tokenEncryptor encrypts at-rest secrets such as third-party OAuth
	// access/refresh tokens. Defaults to bridge.NoopEncryptor when no
	// AUTHSOME_TOKEN_ENCRYPTION_KEY is configured (dev mode).
	tokenEncryptor bridge.Encryptor

	// Ceremony state store for multi-instance auth ceremonies
	ceremonyStore ceremony.Store

	// RFC 9449 DPoP: proof validator (always constructed), nonce signer
	// (nil when no signing secret is derivable) and replay cache.
	dpopValidator   *dpop.Validator
	dpopNonceSigner *dpop.NonceSigner
	dpopReplayCache dpop.ReplayCache

	// Token format (default: opaque; per-app overrides via AppSessionConfig.TokenFormat)
	defaultTokenFormat tokenformat.Format
	jwtFormats         map[string]*tokenformat.JWT // keyed by app ID

	// Security
	rateLimiter     ratelimit.Limiter
	lockout         lockout.Tracker
	passwordHistory account.PasswordHistoryStore

	// Dynamic settings manager (optional).
	settingsMgr *settings.Manager

	// Bootstrap configuration (nil = disabled).
	bootstrapCfg  *BootstrapConfig
	platformAppID id.AppID
	// ownerMu serialises platform-owner promotion so two users verifying at
	// the same instant cannot both claim the last owner slot.
	ownerMu sync.Mutex

	// dummyHashObserver is a test seam; see SetDummyHashObserver.
	dummyHashObserver func(account.PasswordPolicy)

	// Database reference for plugins that need direct database access
	// to create their own persistent stores.
	db *grove.DB

	// Cached auth middleware — built once during InitPlugins() with full
	// capability detection (JWT + strategies + cookie bridge). Held in an
	// atomic so the lazy middleware AuthMiddleware hands out before then can
	// read it from request goroutines.
	authMiddleware atomic.Pointer[forge.Middleware]

	// Forge auth provider registry — plugins register their providers here.
	authRegistry auth.Registry

	pluginsInitialized bool
	started            atomic.Bool

	// background counts the goroutines the engine started (legacy token
	// hashing, webhook adoption, the retention sweeper) so Stop can wait
	// for them instead of leaving them writing to a store that is closing.
	background sync.WaitGroup
}

// spawn runs fn on a goroutine Stop waits for.
func (e *Engine) spawn(fn func()) {
	e.background.Add(1)
	go func() {
		defer e.background.Done()
		fn()
	}()
}

// waitBackground blocks until every background goroutine has returned or
// ctx is done, and reports whether they all returned.
func (e *Engine) waitBackground(ctx context.Context) bool {
	done := make(chan struct{})
	go func() {
		e.background.Wait()
		close(done)
	}()
	select {
	case <-done:
		return true
	case <-ctx.Done():
		return false
	}
}

// NewEngine creates a new AuthSome engine with the given options.
func NewEngine(opts ...Option) (*Engine, error) {
	e := &Engine{
		config: DefaultConfig(),
		logger: log.NewNoopLogger(),
	}

	for _, opt := range opts {
		opt(e)
	}

	if e.store == nil {
		return nil, errors.New("authsome: store is required")
	}
	if e.chronicle == nil {
		return nil, ErrChronicleRequired
	}
	// Causes of generic 500s are logged here, keyed by request id.
	middleware.SetInternalErrorLogger(e.logger)
	if e.wardenEng == nil {
		return nil, errors.New("authsome: warden engine is required (use WithWarden option)")
	}

	// Stamp session roles on the way to the store, before any subsystem below
	// captures a reference to it. Sessions are created from six different
	// paths and all of them end at store.CreateSession, so this is the one
	// place that covers every one of them. See engine_session_roles.go.
	e.store = newRoleStampingStore(e.store, e.sessionRoleSlugs, e.logger)

	// Shared abuse state lives in the store's KV table unless the caller
	// wired something else, so limits, locks and ceremonies hold across every
	// replica that shares the database. Allocated here, never lazily on a
	// request goroutine.
	if e.ceremonyStore == nil {
		e.ceremonyStore = ceremony.NewKV(e.store)
	}
	if e.rateLimiter == nil && e.config.RateLimit.Enabled {
		e.rateLimiter = ratelimit.NewKVLimiter(e.store)
	}
	if e.lockout == nil && e.config.Lockout.Enabled {
		e.lockout = lockout.NewKVTracker(e.store,
			lockout.WithMaxAttempts(e.config.Lockout.MaxAttempts),
			lockout.WithLockoutDuration(e.config.Lockout.LockoutDuration()),
			lockout.WithResetAfter(e.config.Lockout.ResetAfter()),
		)
	}

	// Initialize subsystems
	e.plugins = plugin.NewRegistry(e.logger)
	e.hooks = hook.NewBus(e.logger)
	e.strategies = strategy.NewRegistry(e.logger)

	// Wire the principal-auth gate. Static API-key traffic (and any other
	// machine credential) reaches strategy.Authenticate directly, bypassing
	// every sign-in hook, so this is what fires OnBeforePrincipalAuth /
	// OnAfterPrincipalAuth for it instead. See plugin_principalauth.go.
	if e.principalAuthTTL <= 0 {
		e.principalAuthTTL = 5 * time.Minute
	}
	e.principalAuthGate = newPrincipalAuthGate(
		e.plugins.EmitBeforePrincipalAuth,
		func(ctx context.Context, a *principal.AuthAttempt, s *session.Session) {
			e.plugins.EmitAfterPrincipalAuth(ctx, a, s)
			e.hooks.Emit(ctx, &hook.Event{
				Action:     hook.ActionPrincipalAuth,
				Resource:   hook.ResourceSession,
				ResourceID: s.ID.String(),
				ActorID:    a.Subject.ID,
				Tenant:     a.AppID.String(),
				Metadata: map[string]string{
					"principal_kind":  string(a.Subject.Kind),
					"credential_kind": a.CredentialKind,
					"credential_id":   a.CredentialID,
					"ip":              a.IPAddress,
				},
			})
		},
		e.principalAuthTTL,
		e.logger,
	)

	// Initialize the dynamic settings manager.
	e.settingsMgr = settings.NewManager(e.store, e.logger)

	// Register core session settings.
	if err := registerCoreSessionSettings(e.settingsMgr); err != nil {
		return nil, fmt.Errorf("authsome: register session settings: %w", err)
	}
	// SameSite=None makes the cookie ride along on cross-site requests; it
	// is only safe with the CSRF check standing in front of them.
	if def := e.settingsMgr.Definition(SettingCookieSameSite.Def.Key); def != nil {
		csrfOn := e.config.CSRF.IsEnabled()
		def.Validate = func(raw json.RawMessage) error {
			var v string
			if err := json.Unmarshal(raw, &v); err != nil {
				return fmt.Errorf("session.cookie_same_site: %w", err)
			}
			if v == "none" && !csrfOn {
				return errors.New("session.cookie_same_site: \"none\" needs the CSRF check on (csrf.enabled)")
			}
			return nil
		}
	}

	// Register captcha settings (Phase 2B.2).
	if err := registerCaptchaSettings(e.settingsMgr); err != nil {
		return nil, fmt.Errorf("authsome: failed to register captcha settings: %w", err)
	}

	// Construct the RFC 9449 DPoP validator and, when a secret is
	// derivable, the nonce signer. Settings and JWT formats (both consulted
	// indirectly, the latter via NonceSecret) are established by this point.
	e.initDPoP()

	// Resolve token encryptor: WithTokenEncryptor wins, then configuration,
	// then the environment. A production boot with no key fails here; only a
	// test process may run without one.
	if e.tokenEncryptor == nil {
		enc, err := resolveTokenEncryptor(e.config.TokenEncryption, e.logger, testing.Testing())
		if err != nil {
			return nil, err
		}
		e.tokenEncryptor = enc
	}

	// The API key pepper is process-wide because key digests are computed
	// by the apikey package wherever a key is minted or checked.
	if pepper := resolveAPIKeyPepper(e.config.APIKeyPepper); pepper != nil {
		apikey.SetPepper(pepper)
	}

	// Register pending plugins
	for _, p := range e.pendingPlugins {
		e.plugins.Register(p)
	}
	e.pendingPlugins = nil

	// Register pending strategies
	for _, ps := range e.pendingStrategies {
		e.strategies.Register(ps.strategy, ps.priority)
	}
	e.pendingStrategies = nil

	return e, nil
}

// ErrNotStarted is returned when a service method is called before Start().
var ErrNotStarted = errors.New("authsome: engine not started, please wait for initialization to complete")

// ErrChronicleRequired is returned by NewEngine when no audit trail was
// configured. Authsome does not run without one: every security-relevant
// action is recorded through Chronicle and there is no fallback sink.
var ErrChronicleRequired = errors.New("authsome: a Chronicle audit trail is required; pass WithChronicle")

// EnsureMigrated runs store migrations (core + plugin groups) if not disabled.
// This is idempotent — safe to call multiple times. Use this to ensure tables
// exist before the engine is fully started (e.g. during extension init).
func (e *Engine) EnsureMigrated(ctx context.Context) error {
	if e.config.DisableMigrate {
		return nil
	}
	extraGroups := e.plugins.CollectMigrationGroups(e.config.DriverName)
	return e.store.Migrate(ctx, extraGroups...)
}

// requireStarted returns ErrNotStarted if the engine has not been started.
func (e *Engine) requireStarted() error {
	if !e.started.Load() {
		return ErrNotStarted
	}
	return nil
}

// DPoPBindingConfig returns the RFC 9449 enforcement wiring, for every auth
// path that resolves a token and therefore has to honour a binding. The auth
// middleware is one such path and the registered session auth provider is
// another; anyone assembling their own chain gets the same config from here
// rather than reassembling one that drifts.
//
// The validator is always non-nil (initDPoP builds it unconditionally); the
// nonce signer is nil until a secret is derivable, which DPoPNonceRequiredForApp
// already accounts for by refusing to demand nonces it cannot mint.
func (e *Engine) DPoPBindingConfig() middleware.SessionBindingConfig {
	return middleware.SessionBindingConfig{
		DPoPValidator:   e.DPoPValidator(),
		DPoPNonceSigner: e.DPoPNonceSigner(),
		DPoPNonceRequired: func(ctx context.Context, appID string) bool {
			parsed, err := id.Parse(appID)
			if err != nil {
				return false
			}
			return e.DPoPNonceRequiredForApp(ctx, parsed)
		},
		DPoPAudit: func(ctx context.Context, action string, md map[string]string) {
			severity := hook.SeverityInfo
			if action == hook.ActionDPoPProofReplayed {
				severity = hook.SeverityWarning
			}
			e.hooks.Emit(ctx, &hook.Event{
				Action:     action,
				Resource:   hook.ResourceSession,
				ResourceID: md["session_id"],
				Tenant:     md["app_id"],
				Severity:   severity,
				Outcome:    hook.OutcomeFailure,
				Category:   "auth",
				Metadata:   md,
			})
		},
	}
}

// buildAuthMiddleware constructs the fully-configured auth middleware with
// capability detection (JWT, strategies) and the cookie-to-header bridge.
// Called once during InitPlugins so both the extension and plugins share
// the same middleware instance.
//
// Strategy registration timing — IMPORTANT: this method runs DURING
// InitPlugins, BEFORE plugin OnInit hooks fire and BEFORE Engine.Start
// auto-registers plugin-provided strategies. So at build time
// `e.HasStrategies()` is always false and `e.Strategies()` returns an
// empty registry. We deliberately ignore HasStrategies as a switch
// guard and always pass the registry pointer into the middleware —
// the registry is allocated up front and the middleware reads it
// lazily on each request, so strategies registered AFTER this build
// are picked up automatically. Choosing the bare `AuthMiddleware`
// variant here would permanently strip strategy support from every
// request and turn every API-key call into a 401 with the unhelpful
// "no strategy ran" debug_reason.
func (e *Engine) buildAuthMiddleware() {
	var inner forge.Middleware

	bindCfg := e.DPoPBindingConfig()
	bindCfg.CookieNameResolver = e.resolveSessionCookieName
	bindCfg.JWTSessionChecker = e.JWTSessionChecker
	bindCfg.JWTSessionContextChecker = e.JWTSessionContextChecker
	bindCfg.ExpectedAudienceResolver = e.resolveExpectedAudience
	bindCfg.PrincipalResolver = e.ResolvePrincipalByRef

	if e.HasJWT() {
		inner = middleware.AuthMiddlewareWithJWT(
			e.ResolveSessionByToken,
			e.ResolveUser,
			e.Strategies(),
			e,
			e.Logger(),
			bindCfg,
		)
	} else {
		// Always pass the strategies registry — even when empty at
		// build time it will be populated by Start before the first
		// request lands. The registry pointer is stable; the
		// middleware iterates it on each request.
		inner = middleware.AuthMiddlewareWithStrategies(
			e.ResolveSessionByToken,
			e.ResolveUser,
			e.Strategies(),
			e.Logger(),
			bindCfg,
		)
	}

	// Wrap with cookie-to-header bridge: when no Authorization header is
	// present, read the auth_token cookie (set during browser login) or
	// the dynamic session cookie and inject it as a Bearer token.
	//
	// The bridge also records the value it wrote. Everything downstream still
	// reads one credential shape, but RFC 9449 section 7.1 is a rule about the
	// Authorization header, and a bound session presented by cookie needs a
	// proof rather than a scheme it has no way to set. Losing that fact in here
	// made every bound cookie session a permanent 401, which since sign-in
	// started binding is every first-party sign-in under mode required.
	var built forge.Middleware = func(next forge.Handler) forge.Handler {
		return func(ctx forge.Context) error {
			r := ctx.Request()
			if r.Header.Get("Authorization") == "" {
				bridged := ""
				if cookie, err := r.Cookie("auth_token"); err == nil && cookie.Value != "" {
					bridged = cookie.Value
				} else {
					// Fall back to the dynamic session cookie name from settings.
					cookieName := e.resolveSessionCookieName(ctx.Context())
					if cookie, err := r.Cookie(cookieName); err == nil && cookie.Value != "" {
						bridged = cookie.Value
					}
				}
				if bridged != "" {
					r.Header.Set("Authorization", "Bearer "+bridged)
					ctx.WithContext(middleware.WithCookieBridgedToken(ctx.Context(), bridged))
				}
			}
			return inner(next)(ctx)
		}
	}
	e.authMiddleware.Store(&built)
}

// AuthMiddleware returns the engine's fully-configured non-blocking
// authentication middleware (cookie bridge + JWT + strategies). Populates
// user context when a valid token is present, passes through otherwise.
// Applied globally by the extension.
//
// It never returns nil. The real middleware is built by InitPlugins (which
// Start calls). Ask for it before that and you get a middleware that looks
// the real one up on every request, so you can mount it while you wire your
// router and it starts authenticating once the engine is initialized. Until
// then it passes requests through unauthenticated, which routes that need a
// signed-in user already refuse.
func (e *Engine) AuthMiddleware() forge.Middleware {
	if mw := e.authMiddleware.Load(); mw != nil {
		return *mw
	}
	return func(next forge.Handler) forge.Handler {
		return func(ctx forge.Context) error {
			if mw := e.authMiddleware.Load(); mw != nil {
				return (*mw)(next)(ctx)
			}
			return next(ctx)
		}
	}
}

// AuthRegistry returns the forge auth provider registry. Plugins can register
// their own auth providers and create middleware via registry.Middleware().
func (e *Engine) AuthRegistry() auth.Registry { return e.authRegistry }

// SetAuthRegistry sets the forge auth provider registry. Called by the
// extension after obtaining the registry from the DI container.
func (e *Engine) SetAuthRegistry(r auth.Registry) { e.authRegistry = r }

// registerSessionAuthProvider registers the core "session" auth provider
// with the forge auth registry. This must be called before plugin OnInit
// so plugins can reference "session" in their auth declarations.
func (e *Engine) registerSessionAuthProvider() {
	if e.authRegistry == nil {
		e.logger.Debug("authsome: no auth registry available, skipping session provider registration")
		return
	}
	provider := authprovider.
		NewSessionProvider(e.ResolveSessionByToken, e.ResolveUser, e.logger, e.resolveSessionCookieName).
		WithDPoP(e.DPoPBindingConfig())
	if err := e.authRegistry.Register(provider); err != nil {
		e.logger.Warn("authsome: failed to register session auth provider",
			log.String("error", err.Error()),
		)
	} else {
		e.logger.Info("authsome: registered 'session' auth provider with forge auth registry")
	}

	// The provider above accepts a bearer header or the session cookie, but
	// one provider declares one security scheme, and its scheme says bearer.
	// Registering the cookie half separately is what puts the browser flow
	// into the OpenAPI document, and therefore into every generated client.
	// Both delegate to the same Authenticate, so they cannot disagree about
	// what a valid session is.
	if err := e.authRegistry.Register(authprovider.NewCookieSessionProvider(provider)); err != nil {
		e.logger.Warn("authsome: failed to register session-cookie auth provider",
			log.String("error", err.Error()),
		)
	} else {
		e.logger.Info("authsome: registered 'session-cookie' auth provider with forge auth registry")
	}
}

// resolveSessionCookieName returns the session cookie name for the given
// context by reading from dynamic settings. Falls back to the default
// "authsome_session_token" when settings are unavailable or unset.
func (e *Engine) resolveSessionCookieName(ctx context.Context) string {
	mgr := e.Settings()
	if mgr == nil {
		return "authsome_session_token"
	}
	opts := settings.ResolveOpts{}
	if appID, ok := middleware.AppIDFrom(ctx); ok {
		opts.AppID = appID.String()
	}
	name, err := settings.Get(ctx, mgr, SettingCookieName, opts)
	if err != nil || name == "" {
		return "authsome_session_token"
	}
	return name
}

// resolveExpectedAudience returns the resource identifiers this deployment
// answers to for the app that minted the presented token, or nil to disable
// the check.
//
// appID comes from the token itself (sess.AppID or claims.AppID), not from the
// request context. resolveSessionCookieName reads the request's app id because
// picking a cookie name is a property of the inbound call, but the audience
// check is a property of the credential. The request only carries an app id
// when PublishableKeyMiddleware ran and the caller sent X-Publishable-Key,
// both optional, so reading it here would let a caller disable the check by
// dropping a header.
//
// The fail-open on a settings error is deliberate. Failing closed would turn a
// settings outage into a total authentication outage across every app, and the
// audience check is a second line of defence sitting behind the token's own
// signature, which has already been verified by the time this runs. Do not
// "harden" this into a fail-closed check without understanding that trade.
func (e *Engine) resolveExpectedAudience(ctx context.Context, appID string) []string {
	mgr := e.Settings()
	if mgr == nil {
		return nil
	}
	opts := settings.ResolveOpts{AppID: appID}
	identifier, err := settings.Get(ctx, mgr, SettingResourceIdentifier, opts)
	if err != nil {
		e.controlDegraded(telemetry.ControlSettings, appID)
		return nil
	}
	if identifier == "" {
		return nil
	}
	return []string{identifier}
}

// JWTSessionChecker checks whether a JWT's session ID still exists in the
// store. This enables JWT revocation: revoked sessions are rejected even if
// the JWT signature is valid. The SettingJWTRequireActiveSession setting,
// resolved under the token's own app, controls whether this check is
// active; when it is off, nil, nil is returned to skip the store lookup and
// the binding checks. The setting defaults to on.
func (e *Engine) JWTSessionChecker(appIDStr, sessionIDStr string) (*session.Session, error) {
	return e.JWTSessionContextChecker(context.Background(), appIDStr, sessionIDStr)
}

// JWTSessionContextChecker is JWTSessionChecker for a caller that has the
// request's context. The lookup runs on context.WithoutCancel(ctx): it
// keeps the request's values, so its queries show up in the request's
// trace, and drops its cancellation and deadline, so it behaves exactly as
// it did on context.Background().
func (e *Engine) JWTSessionContextChecker(ctx context.Context, appIDStr, sessionIDStr string) (*session.Session, error) {
	ctx = context.WithoutCancel(ctx)

	// Check if the feature is enabled via dynamic settings.
	mgr := e.Settings()
	if mgr != nil {
		opts := settings.ResolveOpts{}
		if appID, err := id.ParseAppID(appIDStr); err == nil && !appID.IsNil() {
			opts.AppID = appID.String()
		}
		enabled, _ := settings.Get(ctx, mgr, SettingJWTRequireActiveSession, opts) //nolint:errcheck // best-effort
		if !enabled {
			return nil, nil //nolint:nilnil // nil,nil signals "feature disabled, skip check"
		}
	}

	sessID, err := id.ParseSessionID(sessionIDStr)
	if err != nil {
		return nil, fmt.Errorf("authsome: invalid session ID in JWT: %w", err)
	}
	return e.store.GetSession(ctx, sessID)
}

// ensureAuthRegistry creates a local in-memory auth registry if no external
// one was provided (e.g. forge auth extension not registered in the app).
// This ensures AuthRegistry() never returns nil and plugins can always
// register providers and create middleware.
func (e *Engine) ensureAuthRegistry() {
	if e.authRegistry != nil {
		return
	}
	e.authRegistry = auth.NewRegistry(nil, e.logger)
	e.logger.Debug("authsome: created local auth registry (forge auth extension not available)")
}

// InitPlugins builds the auth middleware, registers the session auth provider,
// and calls OnInit on all registered plugins. Idempotent — safe to call
// multiple times. The extension calls this before route registration so
// plugins can set up dependencies that RegisterRoutes relies on.
// A plugin whose OnInit fails aborts initialization: pluginsInitialized stays
// false so a caller that recovers can retry, and the error propagates rather
// than leaving the engine running with that plugin's control absent.
func (e *Engine) InitPlugins(ctx context.Context) error {
	if e.pluginsInitialized {
		return nil
	}
	e.buildAuthMiddleware()
	e.ensureAuthRegistry()
	e.registerSessionAuthProvider()
	if err := e.plugins.EmitOnInit(ctx, e); err != nil {
		return fmt.Errorf("authsome: init plugins: %w", err)
	}
	e.pluginsInitialized = true
	return nil
}

// Start initializes the engine, runs migrations, and starts plugins.
func (e *Engine) Start(ctx context.Context) error {
	if e.started.Load() {
		return nil
	}

	// Run store migrations (idempotent — may have been called earlier via EnsureMigrated).
	if err := e.EnsureMigrated(ctx); err != nil {
		return err
	}
	// Credentials written before token hashing are converted in the
	// background: lookups already upgrade a row on first use, so nothing
	// waits on the sweep, and a large table must not hold up boot. The
	// start context's values travel with the sweep but its cancellation
	// does not, since Start returning is not a reason to stop converting.
	// Its span does not travel either: forge runs Start inside a boot span,
	// and every query the sweep makes would otherwise hang off a trace that
	// ended at startup.
	sweepCtx := telemetry.Detach(context.WithoutCancel(ctx))
	e.spawn(func() { e.hashLegacyTokens(sweepCtx) })
	// Webhook rows from before webhooks became Relay endpoints are given
	// one in the background, for the same reasons.
	e.spawn(func() { e.adoptLegacyWebhooks(sweepCtx) })

	// Register webhook event catalog with relay (before bootstrap so
	// events emitted during bootstrap are recognized).
	if e.relay != nil {
		if err := e.relay.RegisterEventTypes(ctx, bridge.WebhookEventCatalog()); err != nil {
			e.logger.Warn("authsome: failed to register webhook event catalog",
				log.String("error", err.Error()),
			)
		}
	}

	// Initialize plugins (idempotent — may have been called earlier by
	// the extension before route registration).
	if err := e.InitPlugins(ctx); err != nil {
		return err
	}

	// Seed per-app session configs (from code options or YAML config).
	for _, cfg := range e.pendingAppSessCfgs {
		if err := e.store.SetAppSessionConfig(ctx, cfg); err != nil {
			e.logger.Warn("authsome: failed to seed app session config",
				log.String("app_id", cfg.AppID.String()),
				log.String("error", err.Error()),
			)
		}
	}
	e.pendingAppSessCfgs = nil

	// Bootstrap platform app (if configured).
	if e.bootstrapCfg != nil {
		if err := e.bootstrap(ctx); err != nil {
			return err
		}
	}

	// Register authsome resource types with Warden (idempotent).
	// This must run AFTER bootstrap so that platformAppID is set and
	// resource types are created with the correct tenant ID.
	if e.wardenEng != nil {
		e.registerWardenResourceTypes(ctx)
	}

	// Distribute the resolved app ID to plugins that need it.
	// This must happen after bootstrap (which may create the platform app).
	if appID := e.config.AppID; appID != "" {
		for _, p := range e.plugins.Plugins() {
			type appIDSetter interface {
				SetAppID(string)
			}
			if s, ok := p.(appIDSetter); ok {
				s.SetAppID(appID)
			}
		}
	}

	// Auto-register strategies from plugins implementing StrategyProvider.
	for _, p := range e.plugins.Plugins() {
		if sp, ok := p.(plugin.StrategyProvider); ok {
			e.strategies.Register(sp.Strategy(), sp.StrategyPriority())
			e.logger.Info("authsome: auto-registered strategy from plugin",
				log.String("plugin", p.Name()),
				log.String("strategy", sp.Strategy().Name()),
			)
		}
	}

	// Auto-register settings from plugins implementing SettingsProvider.
	for _, p := range e.plugins.Plugins() {
		if sp, ok := p.(plugin.SettingsProvider); ok {
			if err := sp.DeclareSettings(e.settingsMgr); err != nil {
				e.logger.Warn("authsome: failed to register plugin settings",
					log.String("plugin", p.Name()),
					log.String("error", err.Error()),
				)
			}
		}
	}

	// Register the audit trail as the first hook handler so a refused record
	// surfaces to EmitCritical callers before anything else runs.
	e.hooks.On("chronicle", func(ctx context.Context, event *hook.Event) error {
		if err := e.chronicle.Record(ctx, auditEventFromHook(event)); err != nil {
			e.logger.Error("authsome: audit record failed",
				log.String("action", event.Action),
				log.String("request_id", event.RequestID),
				log.String("error", err.Error()),
			)
			if e.metrics != nil {
				e.metrics.IncrementCounter("audit.record.failed", event.Tenant)
			}
			e.tel.AuditRecordFailed()
			return err
		}
		return nil
	})

	// Register metrics collector as a hook handler
	if e.metrics != nil {
		e.hooks.On("metrics", func(_ context.Context, event *hook.Event) error {
			e.metrics.RecordEvent(event.Action, event.Resource, event.Outcome, event.Tenant, 0)
			return nil
		})
	}
	// Count every bus event in the sink too, by action, resource and
	// outcome only: never by tenant, which is an app ID and unbounded.
	if e.tel != nil {
		e.hooks.On("telemetry", func(_ context.Context, event *hook.Event) error {
			e.tel.Event(event.Action, event.Resource, event.Outcome)
			return nil
		})
	}

	// Expired rows are swept on a timer for as long as the engine runs;
	// see engine_retention.go. As with the token sweep above, the start
	// context's cancellation is not a reason to stop, and its boot span is
	// dropped so each sweep can be its own trace.
	e.startRetentionSweeper(telemetry.Detach(context.WithoutCancel(ctx)))

	e.started.Store(true)
	return nil
}

// auditEventFromHook maps a bus event to the audit sink's shape. Private is
// deliberately not copied: it exists so a token can reach a notification
// handler without being written to the trail.
func auditEventFromHook(event *hook.Event) *bridge.AuditEvent {
	return &bridge.AuditEvent{
		Action:     event.Action,
		Resource:   event.Resource,
		ResourceID: event.ResourceID,
		ActorID:    event.ActorID,
		Tenant:     event.Tenant,
		OrgID:      event.OrgID,
		Outcome:    event.Outcome,
		Severity:   event.Severity,
		Category:   event.Category,
		Metadata:   event.Metadata,
		Reason:     event.Reason,
		IP:         event.IP,
		UserAgent:  event.UserAgent,
		RequestID:  event.RequestID,
		SessionID:  event.SessionID,
	}
}

// Health checks the health of the engine by pinging its store.
func (e *Engine) Health(ctx context.Context) error {
	return e.store.Ping(ctx)
}

// Stop gracefully shuts down the engine and all plugins.
func (e *Engine) Stop(ctx context.Context) error {
	if !e.started.Swap(false) {
		return nil
	}
	e.stopRetentionSweeper()
	if !e.waitBackground(ctx) {
		e.logger.Warn("authsome: stop: background work still running at deadline")
	}
	e.plugins.EmitOnShutdown(ctx)
	return nil
}

// registerWardenResourceTypes registers authsome's default resource type
// schemas with the Warden store. The operation is idempotent — duplicate
// errors are silently ignored.
func (e *Engine) registerWardenResourceTypes(ctx context.Context) {
	tenantID := e.config.AppID
	if !e.platformAppID.IsNil() {
		tenantID = e.platformAppID.String()
	}

	for _, schema := range authz.DefaultSchemas() {
		rt := &resourcetype.ResourceType{
			ID:          wardenid.NewResourceTypeID(),
			TenantID:    tenantID,
			AppID:       tenantID,
			Name:        schema.Name,
			Description: schema.Description,
			Relations:   schema.Relations,
			Permissions: schema.Permissions,
		}
		if err := e.wardenEng.Store().CreateResourceType(ctx, rt); err != nil {
			// Idempotent — ignore duplicate/already-exists errors.
			e.logger.Debug("authsome: resource type may already exist",
				log.String("name", schema.Name),
				log.String("error", err.Error()),
			)
		}
	}
	e.logger.Info("authsome: warden resource types registered",
		log.Int("count", len(authz.DefaultSchemas())),
	)
}

// ──────────────────────────────────────────────────
// Accessors
// ──────────────────────────────────────────────────

// Compile-time check: *Engine must satisfy plugin.Engine.
var _ plugin.Engine = (*Engine)(nil)

// Store returns the persistence backend.
func (e *Engine) Store() store.Store { return e.store }

// GetUser returns a user by ID. This method allows the Engine to satisfy
// narrow interfaces (e.g. notification plugin's userLookup) without
// exposing the full store.
func (e *Engine) GetUser(ctx context.Context, userID id.UserID) (*user.User, error) {
	return e.store.GetUser(ctx, userID)
}

// GetUserByEmail looks up a user by any of their email addresses (primary or
// secondary) within an app. Returns store.ErrNotFound when no match exists.
func (e *Engine) GetUserByEmail(ctx context.Context, appID id.AppID, email string) (*user.User, error) {
	return e.store.GetUserByAnyEmail(ctx, appID, id.Nil, email)
}

// Plugins returns the plugin registry.
func (e *Engine) Plugins() *plugin.Registry { return e.plugins }

// Plugin returns a registered plugin by name, or nil if not found.
func (e *Engine) Plugin(name string) plugin.Plugin { return e.plugins.Plugin(name) }

// Hooks returns the global event bus.
func (e *Engine) Hooks() *hook.Bus { return e.hooks }

// SwitchActiveOrg sets the active organization on an existing session.
// The session's user must be a member of newOrgID — verified via the
// organization plugin. When the user is not a member the org-plugin
// returns ErrOrgNotMember (or equivalent) and we propagate.
//
// Returns the updated session so callers (HTTP handlers) can re-issue
// the cookie / token with the new OrgID claim if appropriate.
//
// When newOrgID is empty the active org is cleared (legitimate use:
// "leave the current org and stay logged out of any org").
func (e *Engine) SwitchActiveOrg(ctx context.Context, sessionID id.SessionID, newOrgID id.OrgID) (*session.Session, error) {
	sess, err := e.store.GetSession(ctx, sessionID)
	if err != nil {
		return nil, fmt.Errorf("authsome: get session: %w", err)
	}

	if !newOrgID.IsNil() {
		// Membership check via the organization plugin. Plugin name is
		// stable so the lookup is cheap; we tolerate the plugin not
		// being registered (auth-only deployments without orgs) by
		// returning a clear error rather than crashing on nil.
		orgP, ok := e.plugins.Plugin("organization").(orgMembershipChecker)
		if !ok || orgP == nil {
			return nil, fmt.Errorf("authsome: organization plugin not registered; cannot switch org")
		}
		orgs, err := orgP.ListUserOrganizations(ctx, sess.UserID)
		if err != nil {
			return nil, fmt.Errorf("authsome: list user orgs for membership check: %w", err)
		}
		matched := false
		for _, o := range orgs {
			if o.ID == newOrgID {
				matched = true
				break
			}
		}
		if !matched {
			return nil, fmt.Errorf("authsome: user is not a member of org %s", newOrgID)
		}
	}

	sess.OrgID = newOrgID
	if err := e.store.UpdateSession(ctx, sess); err != nil {
		return nil, fmt.Errorf("authsome: update session: %w", err)
	}

	e.hooks.Emit(ctx, &hook.Event{
		Action:     hook.ActionSessionCreate, // closest semantic action; bespoke ActionSessionSwitchOrg can be added later
		Resource:   hook.ResourceSession,
		ResourceID: sess.ID.String(),
		ActorID:    sess.UserID.String(),
		Tenant:     newOrgID.String(),
		Metadata:   map[string]string{"event": "switch_active_org"},
		Category:   hook.CategoryAuth,
	})

	return sess, nil
}

// orgMembershipChecker is the narrow contract SwitchActiveOrg needs
// from the organization plugin. Defined locally so the engine doesn't
// import plugins/organization (would create a cycle).
type orgMembershipChecker interface {
	ListUserOrganizations(ctx context.Context, userID id.UserID) ([]*organization.Organization, error)
}

// DefaultAppID returns the configured app ID string.
func (e *Engine) DefaultAppID() string { return e.config.AppID }

// BasePath returns the URL prefix for auth routes.
func (e *Engine) BasePath() string { return e.config.BasePath }

// Strategies returns the strategy registry.
func (e *Engine) Strategies() *strategy.Registry { return e.strategies }

// HasStrategies returns true if any authentication strategies are registered.
func (e *Engine) HasStrategies() bool { return len(e.strategies.Strategies()) > 0 }

// Logger returns the engine logger.
func (e *Engine) Logger() log.Logger { return e.logger }

// Config returns the engine configuration.
func (e *Engine) Config() Config { return e.config }

// SessionConfigForApp returns the resolved session config for an app,
// applying per-app and optional per-environment overrides on top of the
// global defaults. Plugins should use this instead of hardcoding their
// own session config.
func (e *Engine) SessionConfigForApp(ctx context.Context, appID id.AppID, envIDs ...id.EnvironmentID) account.SessionConfig {
	return e.sessionConfigForApp(ctx, appID, envIDs...)
}

// Chronicle returns the audit trail bridge (may be nil).
func (e *Engine) Chronicle() bridge.Chronicle { return e.chronicle }

// SetChronicle replaces the chronicle implementation. Intended for tests;
// not safe for concurrent use after Start.
func (e *Engine) SetChronicle(ch bridge.Chronicle) {
	// A test seam only. Production code never swaps the audit sink after
	// construction; importing "testing" registers no flags, so the check
	// costs nothing outside test binaries.
	if !testing.Testing() {
		panic("authsome: SetChronicle is only available in tests")
	}
	e.chronicle = ch
}

// SetRateLimiter replaces the rate limiter. A test seam only, like
// SetChronicle: tests relax the on-by-default limits without rebuilding the
// engine's configuration.
func (e *Engine) SetRateLimiter(rl ratelimit.Limiter) {
	if !testing.Testing() {
		panic("authsome: SetRateLimiter is only available in tests")
	}
	e.rateLimiter = rl
}

// SetLockoutTracker replaces the lockout tracker. A test seam only.
func (e *Engine) SetLockoutTracker(t lockout.Tracker) {
	if !testing.Testing() {
		panic("authsome: SetLockoutTracker is only available in tests")
	}
	e.lockout = t
}

// Authorizer returns the authorization bridge (may be nil).
func (e *Engine) Authorizer() bridge.Authorizer { return e.authorizer }

// KeyManager returns the key management bridge (may be nil).
func (e *Engine) KeyManager() bridge.KeyManager { return e.keyManager }

// Relay returns the event relay bridge (may be nil).
func (e *Engine) Relay() bridge.EventRelay { return e.relay }

// Mailer returns the email bridge (may be nil). Each send through it is a
// send email span and an observation in the provider latency histogram,
// whichever Mailer was configured; the no-op mailer is handed back as is.
func (e *Engine) Mailer() bridge.Mailer {
	switch e.mailer.(type) {
	case nil, *bridge.NoopMailer:
		return e.mailer
	}
	return tracedMailer{next: e.mailer, tel: e.tel}
}

// SMSSender returns the SMS bridge (may be nil), traced and measured the
// same way as Mailer.
func (e *Engine) SMSSender() bridge.SMSSender {
	switch e.sms.(type) {
	case nil, *bridge.NoopSMSSender:
		return e.sms
	}
	return tracedSMSSender{next: e.sms, tel: e.tel}
}

// Herald returns the Herald notification bridge (may be nil).
func (e *Engine) Herald() bridge.Herald { return e.heraldBridge }

// Vault returns the secrets/feature-flag/config bridge (may be nil).
func (e *Engine) Vault() bridge.Vault { return e.vault }

// TokenEncryptor returns the at-rest Encryptor used for sensitive opaque
// payloads such as third-party OAuth access/refresh tokens. Always non-nil
// after NewEngine: a boot with no key configured fails rather than falling
// back to plaintext, except under `go test`. Plugins that persist provider
// tokens should wrap their store using this encryptor (see
// plugins/social.NewEncryptedStore).
func (e *Engine) TokenEncryptor() bridge.Encryptor {
	if e.tokenEncryptor == nil {
		return bridge.NoopEncryptor{}
	}
	return e.tokenEncryptor
}

// LegacyPlaintextSecretReads reports how many stored secrets have been read
// back without an encryption envelope since this process started: rows
// written before at-rest encryption was deployed. When it stays at zero
// across a full cycle of the workload, every such row has been rewritten and
// Config.TokenEncryption.Strict can be turned on.
func (e *Engine) LegacyPlaintextSecretReads() uint64 { return bridge.LegacyPlaintextReads() }

// Dispatcher returns the job queue bridge (may be nil).
func (e *Engine) Dispatcher() bridge.Dispatcher { return e.dispatcher }

// Ledger returns the billing/metering bridge (may be nil).
func (e *Engine) Ledger() bridge.Ledger { return e.ledger }

// LedgerEngine returns the first-class ledger billing engine (may be nil).
func (e *Engine) LedgerEngine() *xledger.Ledger { return e.ledgerEng }

// LedgerStore returns the underlying ledger store for direct query access
// (e.g. plan/feature/subscription listing). Returns nil if no ledger engine
// was provided via WithLedgerEngine.
func (e *Engine) LedgerStore() ledgerstore.Store {
	if e.ledgerEng != nil {
		return e.ledgerEng.Store()
	}
	return nil
}

// SetLedgerEngine wires a ledger engine into the authsome engine after
// construction. This is the late-binding counterpart to WithLedgerEngine,
// intended for hosts that cannot resolve the ledger at engine-build time
// (typical when both authsome and ledger live in a DI container whose
// registration order is not guaranteed).
//
// It also updates the bridge.Ledger adapter so hook-based consumers see a
// real ledger instead of the noop. Callers are still responsible for
// propagating the new ledger to plugins that captured their own reference
// during OnInit — see Engine.rebindLedgerOnPlugins.
func (e *Engine) SetLedgerEngine(l *xledger.Ledger) {
	e.ledgerEng = l
	if l != nil {
		e.ledger = ledgeradapter.New(l)
	}
}

// ledgerRebindable is the optional interface implemented by plugins that
// captured a ledger reference during OnInit and need to be notified when
// the engine's ledger is rebound after construction.
type ledgerRebindable interface {
	SetLedger(*xledger.Ledger)
	SetLedgerStore(ledgerstore.Store)
}

// RebindLedgerOnPlugins pushes the engine's current ledger engine and store
// into any plugin that implements SetLedger / SetLedgerStore. Safe to call
// multiple times; no-op when the engine has no ledger.
func (e *Engine) RebindLedgerOnPlugins() {
	if e.ledgerEng == nil || e.plugins == nil {
		return
	}
	ledgerStore := e.ledgerEng.Store()
	for _, p := range e.plugins.Plugins() {
		if rb, ok := p.(ledgerRebindable); ok {
			rb.SetLedger(e.ledgerEng)
			rb.SetLedgerStore(ledgerStore)
		}
	}
}

// MetricsCollector returns the metrics collector bridge (may be nil).
func (e *Engine) MetricsCollector() bridge.MetricsCollector { return e.metrics }

// CeremonyStore returns the ceremony state store for short-lived auth
// ceremony sessions. Returns an in-memory store if none was configured.
func (e *Engine) CeremonyStore() ceremony.Store {
	if e.ceremonyStore != nil {
		return e.ceremonyStore
	}
	return ceremony.NewMemory()
}

// RateLimiter returns the rate limiter (may be nil).
func (e *Engine) RateLimiter() ratelimit.Limiter { return e.rateLimiter }

// ProtectedResourceMetadataURL returns the configured RFC 9728 metadata URL.
func (e *Engine) ProtectedResourceMetadataURL() string {
	return e.config.ProtectedResourceMetadataURL
}

// Lockout returns the account lockout tracker (may be nil).
func (e *Engine) Lockout() lockout.Tracker { return e.lockout }

// PasswordHistory returns the password history store (may be nil).
func (e *Engine) PasswordHistory() account.PasswordHistoryStore { return e.passwordHistory }

// Warden returns the first-class authorization engine (may be nil).
func (e *Engine) Warden() *warden.Engine { return e.wardenEng }

// Keysmith returns the first-class key management engine (may be nil).
func (e *Engine) Keysmith() *keysmith.Engine { return e.keysmithEng }

// Settings returns the dynamic settings manager (may be nil).
func (e *Engine) Settings() *settings.Manager { return e.settingsMgr }

// DB returns the database handle so plugins can create their own persistent
// stores. Returns nil if not set.
func (e *Engine) DB() *grove.DB { return e.db }

// ──────────────────────────────────────────────────
// Client configuration types
// ──────────────────────────────────────────────────

// ClientConfigResponse is the public client-facing configuration returned
// by the /client-config endpoint. It tells the frontend SDK which auth
// methods are enabled, available providers, branding, etc.
type ClientConfigResponse struct {
	Version             string                         `json:"version"`
	AppID               string                         `json:"app_id"`
	SignupEnabled       bool                           `json:"signup_enabled"`
	Branding            *ClientConfigBranding          `json:"branding,omitempty"`
	Password            *ClientConfigToggle            `json:"password,omitempty"`
	Social              *ClientConfigSocial            `json:"social,omitempty"`
	Passkey             *ClientConfigToggle            `json:"passkey,omitempty"`
	MFA                 *ClientConfigMFA               `json:"mfa,omitempty"`
	MagicLink           *ClientConfigToggle            `json:"magiclink,omitempty"`
	SSO                 *ClientConfigSSO               `json:"sso,omitempty"`
	EmailVerification   *ClientConfigEmailVerification `json:"email_verification,omitempty"`
	DeviceAuthorization *ClientConfigToggle            `json:"device_authorization,omitempty"`
	Waitlist            *ClientConfigToggle            `json:"waitlist,omitempty"`
	Captcha             *ClientConfigCaptcha           `json:"captcha,omitempty"`
	SupportedPlugins    []string                       `json:"supported_plugins"`
	SignupFields        []ClientConfigSignupField      `json:"signup_fields,omitempty"`
}

// ClientConfigCaptcha tells the frontend whether — and how — to render
// a captcha challenge before submitting auth forms. Mirrors the
// auth.captcha_* settings; only public-safe fields are exposed (the
// secret_key is intentionally NOT included).
type ClientConfigCaptcha struct {
	Required bool   `json:"required"`
	Provider string `json:"provider,omitempty"`
	SiteKey  string `json:"site_key,omitempty"`
}

// ClientConfigEmailVerification represents email verification settings.
type ClientConfigEmailVerification struct {
	Enabled  bool `json:"enabled"`
	Required bool `json:"required"`
}

// ClientConfigBranding holds app branding information.
type ClientConfigBranding struct {
	AppName string `json:"app_name,omitempty"`
	LogoURL string `json:"logo_url,omitempty"`
}

// ClientConfigToggle represents a simple enabled/disabled auth method.
type ClientConfigToggle struct {
	Enabled bool `json:"enabled"`
}

// ClientConfigSocial represents the social auth configuration.
type ClientConfigSocial struct {
	Enabled   bool                         `json:"enabled"`
	Providers []ClientConfigSocialProvider `json:"providers"`
}

// ClientConfigSocialProvider represents a social login provider.
type ClientConfigSocialProvider struct {
	ID   string `json:"id"`
	Name string `json:"name"`
}

// ClientConfigMFA represents the MFA configuration.
type ClientConfigMFA struct {
	Enabled  bool     `json:"enabled"`
	Required bool     `json:"required"`
	Methods  []string `json:"methods"`
}

// ClientConfigSSO represents the SSO configuration.
type ClientConfigSSO struct {
	Enabled     bool                        `json:"enabled"`
	Connections []ClientConfigSSOConnection `json:"connections"`
}

// ClientConfigSSOConnection represents an SSO connection/provider.
type ClientConfigSSOConnection struct {
	ID   string `json:"id"`
	Name string `json:"name"`
}

// ClientConfigSignupField describes a custom signup form field.
type ClientConfigSignupField struct {
	Key         string                       `json:"key"`
	Label       string                       `json:"label"`
	Type        string                       `json:"type"`
	Placeholder string                       `json:"placeholder,omitempty"`
	Description string                       `json:"description,omitempty"`
	Options     []ClientConfigSelectOption   `json:"options,omitempty"`
	Default     string                       `json:"default,omitempty"`
	Validation  *ClientConfigFieldValidation `json:"validation,omitempty"`
	Order       int                          `json:"order"`
}

// ClientConfigSelectOption represents a select/radio option.
type ClientConfigSelectOption struct {
	Label string `json:"label"`
	Value string `json:"value"`
}

// ClientConfigFieldValidation defines validation rules for a signup field.
type ClientConfigFieldValidation struct {
	Required bool   `json:"required,omitempty"`
	MinLen   int    `json:"min_len,omitempty"`
	MaxLen   int    `json:"max_len,omitempty"`
	Pattern  string `json:"pattern,omitempty"`
	Min      *int   `json:"min,omitempty"`
	Max      *int   `json:"max,omitempty"`
}

// socialProviderLister is implemented by the social plugin to expose providers.
type socialProviderLister interface {
	Providers() []string
}

// ssoConnectionLister is implemented by the SSO plugin to expose connections.
type ssoConnectionLister interface {
	Connections() []string
}

// providerDisplayNames maps lowercase provider IDs to proper display names
// for the client-config response. The frontend renders these as button labels.
var providerDisplayNames = map[string]string{
	"google": "Google", "github": "GitHub", "apple": "Apple",
	"microsoft": "Microsoft", "facebook": "Facebook", "twitter": "Twitter",
	"discord": "Discord", "slack": "Slack", "linkedin": "LinkedIn",
	"gitlab": "GitLab", "bitbucket": "Bitbucket", "spotify": "Spotify",
	"twitch": "Twitch", "dropbox": "Dropbox", "amazon": "Amazon",
	"yahoo": "Yahoo", "line": "Line", "instagram": "Instagram",
	"pinterest": "Pinterest", "patreon": "Patreon", "strava": "Strava",
	"zoom": "Zoom", "okta": "Okta", "azure-ad": "Azure AD",
	"auth0": "Auth0", "onelogin": "OneLogin", "ping": "Ping Identity",
}

func providerDisplayName(providerID string) string {
	if name, ok := providerDisplayNames[providerID]; ok {
		return name
	}
	if providerID == "" {
		return providerID
	}
	return strings.ToUpper(providerID[:1]) + providerID[1:]
}

// ClientConfig returns the merged client-facing configuration for an app.
// This aggregates plugin-level defaults with per-app overrides.
func (e *Engine) ClientConfig(ctx context.Context, appID id.AppID) *ClientConfigResponse {
	resp := &ClientConfigResponse{
		Version: "1",
		AppID:   appID.String(),
	}

	// Load app record for branding defaults.
	if a, err := e.store.GetApp(ctx, appID); err == nil {
		resp.Branding = &ClientConfigBranding{
			AppName: a.Name,
			LogoURL: a.Logo,
		}
	}

	// Detect enabled auth methods from registered plugins.
	allPlugins := e.plugins.Plugins()
	var (
		passwordEnabled  bool
		socialEnabled    bool
		passkeyEnabled   bool
		mfaEnabled       bool
		mfaRequired      bool
		magicLinkEnabled bool
		ssoEnabled       bool
		waitlistEnabled  bool
		socialProviders  []ClientConfigSocialProvider
		ssoConnections   []ClientConfigSSOConnection
		mfaMethods       []string
		pluginNames      = make([]string, 0, len(allPlugins))
	)

	for _, p := range allPlugins {
		name := p.Name()
		pluginNames = append(pluginNames, name)

		switch name {
		case "password":
			passwordEnabled = true
		case "social":
			socialEnabled = true
			if lister, ok := p.(socialProviderLister); ok {
				for _, prov := range lister.Providers() {
					socialProviders = append(socialProviders, ClientConfigSocialProvider{
						ID:   prov,
						Name: providerDisplayName(prov),
					})
				}
			}
		case "passkey":
			passkeyEnabled = true
		case "mfa":
			mfaEnabled = true
			mfaMethods = []string{"totp"}
		case "magiclink":
			magicLinkEnabled = true
		case "sso":
			ssoEnabled = true
			if lister, ok := p.(ssoConnectionLister); ok {
				for _, name := range lister.Connections() {
					ssoConnections = append(ssoConnections, ClientConfigSSOConnection{
						ID:   name,
						Name: providerDisplayName(name),
					})
				}
			}
		case "waitlist":
			waitlistEnabled = true
		}
	}

	// Load per-app overrides and apply on top of plugin defaults.
	if overrides, err := e.store.GetAppClientConfig(ctx, appID); err == nil {
		applyClientConfigOverrides(resp, overrides,
			&passwordEnabled, &socialEnabled, &passkeyEnabled,
			&mfaEnabled, &magicLinkEnabled, &ssoEnabled,
			&waitlistEnabled,
			&socialProviders, &ssoConnections, &mfaMethods,
		)
		if overrides.MFARequired != nil {
			mfaRequired = *overrides.MFARequired
		}
	}

	// Signup is enabled by default unless explicitly disabled.
	resp.SignupEnabled = true

	// Build response sections.
	resp.Password = &ClientConfigToggle{Enabled: passwordEnabled}
	resp.Passkey = &ClientConfigToggle{Enabled: passkeyEnabled}
	resp.MagicLink = &ClientConfigToggle{Enabled: magicLinkEnabled}

	if socialProviders == nil {
		socialProviders = []ClientConfigSocialProvider{}
	}
	resp.Social = &ClientConfigSocial{
		Enabled:   socialEnabled,
		Providers: socialProviders,
	}

	if mfaMethods == nil {
		mfaMethods = []string{}
	}
	resp.MFA = &ClientConfigMFA{
		Enabled:  mfaEnabled,
		Required: mfaRequired,
		Methods:  mfaMethods,
	}

	if ssoConnections == nil {
		ssoConnections = []ClientConfigSSOConnection{}
	}
	resp.SSO = &ClientConfigSSO{
		Enabled:     ssoEnabled,
		Connections: ssoConnections,
	}

	resp.Waitlist = &ClientConfigToggle{Enabled: waitlistEnabled}

	if pluginNames == nil {
		pluginNames = []string{}
	}
	resp.SupportedPlugins = pluginNames

	// Load active signup form config and expose fields.
	if fc, err := e.store.GetFormConfig(ctx, appID, formconfig.FormTypeSignup); err == nil && fc != nil && fc.Active && len(fc.Fields) > 0 {
		fields := make([]ClientConfigSignupField, 0, len(fc.Fields))
		for _, f := range fc.Fields {
			sf := ClientConfigSignupField{
				Key:         f.Key,
				Label:       f.Label,
				Type:        string(f.Type),
				Placeholder: f.Placeholder,
				Description: f.Description,
				Default:     f.Default,
				Order:       f.Order,
			}
			if len(f.Options) > 0 {
				opts := make([]ClientConfigSelectOption, 0, len(f.Options))
				for _, o := range f.Options {
					opts = append(opts, ClientConfigSelectOption{Label: o.Label, Value: o.Value})
				}
				sf.Options = opts
			}
			if f.Validation != (formconfig.Validation{}) {
				sf.Validation = &ClientConfigFieldValidation{
					Required: f.Validation.Required,
					MinLen:   f.Validation.MinLen,
					MaxLen:   f.Validation.MaxLen,
					Pattern:  f.Validation.Pattern,
					Min:      f.Validation.Min,
					Max:      f.Validation.Max,
				}
			}
			fields = append(fields, sf)
		}
		resp.SignupFields = fields
	}

	// Email verification: enabled when password plugin is registered,
	// required based on environment settings (default: required in production).
	if passwordEnabled {
		emailVerifRequired := true
		if env, _ := e.GetDefaultEnvironment(ctx, appID); env != nil && env.Settings != nil { //nolint:errcheck // best-effort env lookup
			if env.Settings.SkipEmailVerification != nil && *env.Settings.SkipEmailVerification {
				emailVerifRequired = false
			}
		}
		resp.EmailVerification = &ClientConfigEmailVerification{
			Enabled:  true,
			Required: emailVerifRequired,
		}
	}

	// Device authorization: enabled when oauth2provider plugin is registered.
	if slices.Contains(pluginNames, "oauth2provider") {
		resp.DeviceAuthorization = &ClientConfigToggle{Enabled: true}
	}

	// Captcha: per-app setting. Always emit the section so the frontend
	// can branch on resp.Captcha.Required without conditional checks.
	// Site key is public by design (visible in the rendered widget); the
	// secret key is loaded server-side only and NEVER returned here.
	resp.Captcha = e.clientConfigCaptcha(ctx, appID)

	return resp
}

// clientConfigCaptcha resolves the public-safe captcha config for an
// app. Returns Required=false / empty fields when settings can't be
// resolved — captcha defaults to off so a settings-store outage never
// locks new signups out.
func (e *Engine) clientConfigCaptcha(ctx context.Context, appID id.AppID) *ClientConfigCaptcha {
	out := &ClientConfigCaptcha{}
	mgr := e.Settings()
	if mgr == nil {
		return out
	}
	resolveOpts := settings.ResolveOpts{AppID: appID.String()}

	if v, err := settings.Get(ctx, mgr, SettingCaptchaRequired, resolveOpts); err == nil {
		out.Required = v
	}
	if v, err := settings.Get(ctx, mgr, SettingCaptchaProvider, resolveOpts); err == nil {
		out.Provider = v
	}
	if v, err := settings.Get(ctx, mgr, SettingCaptchaSiteKey, resolveOpts); err == nil {
		out.SiteKey = v
	}
	return out
}

// applyClientConfigOverrides applies per-app overrides to the client config.
func applyClientConfigOverrides(
	resp *ClientConfigResponse,
	cfg *appclientconfig.Config,
	passwordEnabled, socialEnabled, passkeyEnabled *bool,
	mfaEnabled, magicLinkEnabled, ssoEnabled *bool,
	waitlistEnabled *bool,
	socialProviders *[]ClientConfigSocialProvider,
	_ *[]ClientConfigSSOConnection,
	mfaMethods *[]string,
) {
	if cfg.SignupEnabled != nil {
		resp.SignupEnabled = *cfg.SignupEnabled
	}
	if cfg.PasswordEnabled != nil {
		*passwordEnabled = *cfg.PasswordEnabled
	}
	if cfg.SocialEnabled != nil {
		*socialEnabled = *cfg.SocialEnabled
	}
	if cfg.PasskeyEnabled != nil {
		*passkeyEnabled = *cfg.PasskeyEnabled
	}
	if cfg.MFAEnabled != nil {
		*mfaEnabled = *cfg.MFAEnabled
	}
	if cfg.MagicLinkEnabled != nil {
		*magicLinkEnabled = *cfg.MagicLinkEnabled
	}
	if cfg.SSOEnabled != nil {
		*ssoEnabled = *cfg.SSOEnabled
	}
	if cfg.WaitlistEnabled != nil {
		*waitlistEnabled = *cfg.WaitlistEnabled
	}

	// Filter social providers to per-app whitelist.
	if len(cfg.SocialProviders) > 0 {
		allowed := make(map[string]bool, len(cfg.SocialProviders))
		for _, name := range cfg.SocialProviders {
			allowed[name] = true
		}
		filtered := make([]ClientConfigSocialProvider, 0, len(cfg.SocialProviders))
		for _, p := range *socialProviders {
			if allowed[p.ID] {
				filtered = append(filtered, p)
			}
		}
		*socialProviders = filtered
	}

	// Filter MFA methods to per-app whitelist.
	if len(cfg.MFAMethods) > 0 {
		*mfaMethods = cfg.MFAMethods
	}

	// Branding overrides.
	if cfg.AppName != nil || cfg.LogoURL != nil {
		if resp.Branding == nil {
			resp.Branding = &ClientConfigBranding{}
		}
		if cfg.AppName != nil {
			resp.Branding.AppName = *cfg.AppName
		}
		if cfg.LogoURL != nil {
			resp.Branding.LogoURL = *cfg.LogoURL
		}
	}
}

// APIKeyStore returns the API key store. When Keysmith is available,
// operations delegate to Keysmith's full key management engine (gaining
// rate limiting, policy enforcement, key rotation, scope management, and
// usage tracking). Otherwise, it returns the composite store's API key methods.
func (e *Engine) APIKeyStore() apikey.Store {
	if e.keysmithEng != nil {
		return apikey.NewKeymithStore(e.keysmithEng)
	}
	return e.store.(apikey.Store) //nolint:errcheck // type assertion
}

// PrincipalAuthGate implements plugin.PrincipalAuthGateProvider. It returns
// any rather than a named type so this package does not have to import a
// plugin package to spell the return type, which would create an import
// cycle with plugins (such as apikey) that need the concrete *Engine type
// for other reasons. Consumers type-assert the result against their own
// narrow gate interface.
func (e *Engine) PrincipalAuthGate() any {
	return e.principalAuthGate
}

// ResolveAppByPublicKey resolves a publishable key (pk_live_...) to an app.
// It first checks the apps table publishable_key column (fast, indexed), then
// falls back to searching Keysmith API key metadata for keys generated via
// the API key plugin.
func (e *Engine) ResolveAppByPublicKey(ctx context.Context, publicKey string) (*app.App, error) {
	// Fast path: apps table publishable_key column.
	if a, err := e.store.GetAppByPublishableKey(ctx, publicKey); err == nil {
		return a, nil
	}

	// Fallback: search Keysmith metadata.
	if e.keysmithEng != nil {
		ks := apikey.NewKeymithStore(e.keysmithEng)
		ak, err := ks.FindByPublicKey(ctx, publicKey)
		if err != nil {
			return nil, fmt.Errorf("resolve publishable key: %w", err)
		}
		return e.store.GetApp(ctx, ak.AppID)
	}

	return nil, errors.New("publishable key not found")
}

// ListUserRoleSlugs returns the slugs of all roles assigned to a user.
// This satisfies the middleware.RoleChecker interface (legacy; prefer PermissionChecker).
func (e *Engine) ListUserRoleSlugs(ctx context.Context, userID id.UserID) ([]string, error) {
	var roles []*rbac.Role
	var err error
	if appID := e.PlatformAppID(); !appID.IsNil() {
		roles, err = e.rbacStore().ListUserRolesForApp(ctx, appID.String(), userID.String())
	} else {
		roles, err = e.rbacStore().ListUserRoles(ctx, userID.String())
	}
	if err != nil {
		return nil, err
	}
	slugs := make([]string, len(roles))
	for i, r := range roles {
		slugs[i] = r.Slug
	}
	return slugs, nil
}

// TokenFormatForApp returns the token format for a specific app.
// Resolution order: per-app JWT format → default format → opaque.
func (e *Engine) TokenFormatForApp(appID string) tokenformat.Format {
	if e.jwtFormats != nil {
		if jwtFmt, ok := e.jwtFormats[appID]; ok {
			return jwtFmt
		}
	}
	if e.defaultTokenFormat != nil {
		return e.defaultTokenFormat
	}
	return tokenformat.Opaque{}
}

// JWTFormats returns all registered JWT formats (for JWKS endpoint).
func (e *Engine) JWTFormats() map[string]*tokenformat.JWT { return e.jwtFormats }

// ValidateJWT tries all registered JWT formats to validate a token.
// This implements middleware.JWTValidator.
func (e *Engine) ValidateJWT(token string) (*tokenformat.TokenClaims, error) {
	// Try each registered JWT format.
	for _, jwtFmt := range e.jwtFormats {
		claims, err := jwtFmt.ValidateAccessToken(token)
		if err == nil {
			return claims, nil
		}
	}
	// Try the default format if it's JWT.
	if e.defaultTokenFormat != nil && e.defaultTokenFormat.Name() == "jwt" {
		return e.defaultTokenFormat.ValidateAccessToken(token)
	}
	return nil, tokenformat.ErrInvalidToken
}

// HasJWT returns true if any JWT format is configured.
func (e *Engine) HasJWT() bool {
	if len(e.jwtFormats) > 0 {
		return true
	}
	return e.defaultTokenFormat != nil && e.defaultTokenFormat.Name() == "jwt"
}

// DefaultTokenFormat returns the default token format (may be nil).
func (e *Engine) DefaultTokenFormat() tokenformat.Format { return e.defaultTokenFormat }

// ──────────────────────────────────────────────────
// Account Linking
// ──────────────────────────────────────────────────

// ListAuthMethods aggregates linked auth methods from all plugins that
// implement AuthMethodContributor. Returns an empty slice if no plugins
// contribute methods.
func (e *Engine) ListAuthMethods(ctx context.Context, userID id.UserID) ([]*plugin.AuthMethod, error) {
	var methods []*plugin.AuthMethod
	for _, p := range e.plugins.Plugins() {
		if contributor, ok := p.(plugin.AuthMethodContributor); ok {
			pm, err := contributor.ListUserAuthMethods(ctx, userID)
			if err != nil {
				e.logger.Warn("authsome: list auth methods failed",
					log.String("plugin", p.Name()),
					log.String("error", err.Error()),
				)
				continue
			}
			methods = append(methods, pm...)
		}
	}
	return methods, nil
}

// UnlinkAuthMethod removes an auth method from a user. It returns an error
// if the method is the last one (cannot unlink all methods) or the plugin
// does not support unlinking.
func (e *Engine) UnlinkAuthMethod(ctx context.Context, userID id.UserID, provider string) error {
	// Safety: count total auth methods to ensure at least one remains.
	allMethods, err := e.ListAuthMethods(ctx, userID)
	if err != nil {
		return fmt.Errorf("authsome: list auth methods: %w", err)
	}
	if len(allMethods) <= 1 {
		return errors.New("authsome: cannot unlink last authentication method")
	}

	// Find the plugin that owns this provider.
	for _, p := range e.plugins.Plugins() {
		if unlinker, ok := p.(plugin.AuthMethodUnlinker); ok {
			if unlinker.CanUnlink(ctx, userID, provider) {
				return unlinker.UnlinkAuthMethod(ctx, userID, provider)
			}
		}
	}

	return fmt.Errorf("authsome: no plugin can unlink provider %q", provider)
}

// ──────────────────────────────────────────────────
// Metrics
// ──────────────────────────────────────────────────

// Metrics returns observable metrics for the engine.
type Metrics struct {
	PluginsLoaded int `json:"plugins_loaded"`
	Strategies    int `json:"strategies"`
}

// NonceSecret returns the dashboard nonce signing secret.
//
// It is derived from the first available HMAC JWT signing key (i.e. an entry
// in jwtFormats whose SigningKey is a []byte) by HMAC-SHA256 with the
// info string "authsome:dashboard:nonce-v1" — a single-step HKDF-Expand
// equivalent that domain-separates the nonce key from the JWT key without
// adding a new dependency.
//
// If no HMAC JWT key is available (e.g. RSA/ES256 only, or no JWT at all),
// it falls back to the AUTHSOME_DASHBOARD_NONCE_SECRET environment variable.
// If that is also empty, it returns nil and the caller (the dashboard
// contributor) is expected to log a warning and either generate a random
// per-process secret or leave the signer uninitialised.
func (e *Engine) NonceSecret() []byte {
	const info = "authsome:dashboard:nonce-v1"

	for _, jwtFmt := range e.jwtFormats {
		if jwtFmt == nil {
			continue
		}
		if key, ok := jwtFmt.HMACKey(); ok && len(key) > 0 {
			h := hmac.New(sha256.New, key)
			h.Write([]byte(info))
			return h.Sum(nil)
		}
	}

	if env := os.Getenv("AUTHSOME_DASHBOARD_NONCE_SECRET"); env != "" {
		// Domain-separate even the env-var path so a future reuse of the
		// same env var elsewhere does not cross-contaminate.
		h := hmac.New(sha256.New, []byte(env))
		h.Write([]byte(info))
		return h.Sum(nil)
	}

	return nil
}

// hkdfLike derives a domain-separated key from base material. Same
// construction NonceSecret already uses for the dashboard, pulled out so
// other subsystems (DPoP) can derive their own key from the same base
// secret under a different info string.
func hkdfLike(base []byte, info string) []byte {
	h := hmac.New(sha256.New, base)
	h.Write([]byte(info))
	return h.Sum(nil)
}

// count adds one to a named counter when a collector is configured.
func (e *Engine) count(name, tenant string) {
	if e.metrics != nil {
		e.metrics.IncrementCounter(name, tenant)
	}
}

// Metrics returns the current engine metrics.
func (e *Engine) Metrics() Metrics {
	return Metrics{
		PluginsLoaded: len(e.plugins.Plugins()),
		Strategies:    len(e.strategies.Strategies()),
	}
}

// hashLegacyTokens sweeps plaintext credential rows into hashes in batches
// until the store reports none left, logging the total. It stops on the
// first error; the next start resumes where it left off, and lookups keep
// upgrading rows one at a time in the meantime.
func (e *Engine) hashLegacyTokens(ctx context.Context) {
	const batch = 500
	var total int64
	for {
		n, err := e.store.HashLegacyTokens(ctx, batch)
		total += n
		if err != nil {
			e.logger.Warn("authsome: hashing legacy credential rows stopped",
				log.Int64("converted", total),
				log.String("error", err.Error()),
			)
			return
		}
		if n == 0 {
			break
		}
	}
	if total > 0 {
		e.logger.Info("authsome: hashed legacy credential rows", log.Int64("converted", total))
	}
}

// envAPIKeyPepper names the server-side secret mixed into API key digests.
// #nosec G101 -- not a credential: an environment variable name.
const envAPIKeyPepper = "AUTHSOME_API_KEY_PEPPER"

// resolveAPIKeyPepper returns the pepper bytes from configuration or the
// environment. A value that is valid hex is decoded; anything else is used
// as given, so an operator may paste either form.
func resolveAPIKeyPepper(configured string) []byte {
	raw := strings.TrimSpace(configured)
	if raw == "" {
		raw = strings.TrimSpace(os.Getenv(envAPIKeyPepper))
	}
	if raw == "" {
		return nil
	}
	if b, err := hex.DecodeString(raw); err == nil && len(b) >= 16 {
		return b
	}
	return []byte(raw)
}