admin

type APICatalogStore = catalogapi.CatalogStore

type APIKeyAuthenticator struct {
	Keys map[string]User // key -> user info
}

type APIKeyManager interface {
	ListKeys() []auth.APIKeySummary
	GenerateKey(def auth.APIKey) (string, error)
	RemoveByName(name string) bool
}

type AuditMetricsQuerier = auditapi.MetricsQuerier

type AuditQuerier = auditapi.EventQuerier

type Authenticator interface {
	Authenticate(r *http.Request) (*User, error)
}

type ConfigStore interface {
	Get(ctx context.Context, key string) (*configstore.Entry, error)
	Set(ctx context.Context, key, value, author string) error
	Delete(ctx context.Context, key, author string) error
	List(ctx context.Context) ([]configstore.Entry, error)
	Changelog(ctx context.Context, limit, offset int) ([]configstore.ChangelogEntry, int, error)
	Mode() string
}

type ConnectionStore interface {
	List(ctx context.Context) ([]platform.ConnectionInstance, error)
	Get(ctx context.Context, kind, name string) (*platform.ConnectionInstance, error)
	Set(ctx context.Context, inst platform.ConnectionInstance) error
	Delete(ctx context.Context, kind, name string) error
}

type Deps struct {
	Config              *platform.Config
	ConfigStore         ConfigStore
	FileDefaults        map[string]string
	PersonaRegistry     PersonaRegistry
	ToolkitRegistry     ToolkitRegistry
	ReloadNotifier      ReloadNotifier
	MCPServer           *mcp.Server
	AuditQuerier        AuditQuerier
	AuditMetricsQuerier AuditMetricsQuerier
	Knowledge           *KnowledgeHandler
	APIKeyManager       APIKeyManager
	BrowserAuth         *browsersession.Authenticator
	DatabaseAvailable   bool
	PlatformTools       []platform.ToolInfo
	AssetStore          portal.AssetStore
	ShareStore          portal.ShareStore
	VersionStore        portal.VersionStore
	S3Client            portal.S3Client
	S3Bucket            string
	ConnectionStore     ConnectionStore
	ConnectionSources   *platform.ConnectionSourceMap
	ToolkitsConfig      map[string]any
	PersonaStore        personastore.Store
	APIKeyStore         platform.APIKeyStore
	// UserStore is the known-users directory (#614). nil disables the
	// /api/v1/admin/users routes (no database configured).
	UserStore          user.Store
	PromptStore        prompt.Store
	PromptRegistrar    PromptRegistrar
	PromptInfoProvider PromptInfoProvider
	FilePersonaNames   map[string]bool
	EnrichmentStore    EnrichmentStore
	EnrichmentEngine   EnrichmentEngine
	// PKCEStore holds in-flight authorization_code+PKCE state between
	// oauth-start and the callback. Required for the OAuth routes: there is
	// no fallback, and oauth-start answers 503 when this is nil. Use a
	// pkcestore.MemoryStore for single-replica deployments and a
	// pkcestore.PostgresStore for HA, where oauth-start and the callback may
	// land on different replicas.
	PKCEStore pkcestore.Store
	// ConnOAuthStore persists OAuth tokens for every connection kind
	// in one shared table (migration 000039's connection_oauth_tokens).
	// The unified connection OAuth handler reads and writes through
	// this; toolkit Authenticators read through it on every outbound
	// request. nil disables the unified OAuth routes.
	ConnOAuthStore connoauth.Store
	// OAuthKinds maps connection kind ("mcp", "api", future kinds) to
	// the per-kind config extractor + post-auth side-effect hook. The
	// unified handler dispatches on the {kind} path parameter through
	// this registry. New connection kinds register here at startup —
	// they do NOT add parallel handler files or token stores.
	OAuthKinds OAuthKindHandlers
	// AuthEvents writes the durable per-connection OAuth-lifecycle
	// audit trail (connect, refresh, rotation, revocation, deletion).
	// nil disables event writes — the admin endpoints still work; the
	// History panel and "what killed my token at 17:54" diagnostics
	// just won't have data. Set this when ConnOAuthStore is set; a
	// platform with no DB has no place to write events anyway.
	AuthEvents *authevents.Writer
	// AuthEventStore is the read surface exposed via the History
	// admin endpoint. Distinct from AuthEvents because writes are
	// nil-safe (best-effort) while reads need a real implementation
	// to return 200 instead of an empty list.
	AuthEventStore authevents.Store
	// APICatalogStore manages OpenAPI spec bundles referenced by
	// api-kind connections via config.catalog_id. nil disables the
	// /api/v1/admin/api-catalogs routes; connection saves still
	// succeed but catalog_id is unvalidated. Wire this in lockstep
	// with the apigateway toolkit's SetCatalogStore so admin writes
	// and toolkit reads share one store.
	APICatalogStore APICatalogStore
	// Embedder is the embedding provider used by the api-catalog
	// admin path to compute per-operation vectors at spec-upsert
	// time. Nil disables the compute-and-store step: spec writes
	// still succeed, but the api-gateway toolkit's semantic and
	// hybrid ranking modes fall back to lexical until the operator
	// wires an embedder and re-saves (or re-embeds) the spec.
	Embedder embedding.Provider

	// EmbedJobs is the Postgres-backed job queue for api-catalog
	// embedding work. The admin handler enqueues jobs on every
	// spec write, cancels them on spec/catalog delete (#998), and
	// lets the worker / reconciler / reaper run the actual
	// embedding pass off the request path. nil when the platform
	// was built without a database; spec writes still succeed in
	// that mode but no embeddings are persisted.
	EmbedJobs catalogindex.Store

	// IndexJobs is the cross-kind read + command surface for the admin
	// Indexing dashboard (per-kind job-state counts, coverage, the job
	// list / drill-down, and the manual re-index action). It serves
	// every index_jobs consumer uniformly, so a new consumer gets
	// dashboard visibility for free. nil when no queue is wired (no
	// database or no configured embedding provider); the dashboard
	// then renders a degraded empty state instead of an error.
	IndexJobs IndexJobsService

	// NotificationSettings persists the admin SMTP configuration (#631).
	// nil disables the /api/v1/admin/settings/smtp routes.
	NotificationSettings smtp.SettingsStore
	// SendTestEmail delivers a test email through the stored SMTP
	// settings. nil disables the test-email route.
	SendTestEmail func(ctx context.Context, to string) error
	// NotificationPrefs reads per-address notification preferences so the
	// SMTP test-send UI can surface a target's opt-out state (#1022). nil
	// disables the recipient-status route.
	NotificationPrefs notification.PrefsStore
	// ReviewQueueAlert persists the knowledge review-queue staleness alert
	// threshold, cooldown, and recipients (#803). nil disables the
	// /api/v1/admin/settings/review-queue-alert routes.
	ReviewQueueAlert reviewalert.SettingsStore
	// NotificationHistory reads the delivery history behind the admin
	// Notifications tab: what was sent, what failed and why. nil disables
	// the /api/v1/admin/notifications routes.
	NotificationHistory NotificationHistory
	// NotificationRetention is how long a resolved queue row survives, shown
	// alongside the history so an admin reads it as a recent window rather
	// than a complete record. Zero omits the claim.
	NotificationRetention time.Duration
}

type EnrichmentEngine interface {
	Sources() *enrichment.SourceRegistry
}

type EnrichmentStore interface {
	List(ctx context.Context, connection, tool string, enabledOnly bool) ([]enrichment.Rule, error)
	Get(ctx context.Context, id string) (*enrichment.Rule, error)
	Create(ctx context.Context, r enrichment.Rule) (enrichment.Rule, error)
	Update(ctx context.Context, r enrichment.Rule) (enrichment.Rule, error)
	Delete(ctx context.Context, id string) error
}

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

type IndexJobsService interface {
	// Kinds returns every registered source kind, sorted.
	Kinds() []string
	// Counts returns the per-state job rollup for one source kind.
	Counts(ctx context.Context, kind string) (*indexjobs.KindCounts, error)
	// Coverage returns the indexed-vs-expected rollup for the kind, or
	// nil when the kind reports no coverage. Returns
	// indexjobs.ErrUnknownKind for an unregistered kind.
	Coverage(ctx context.Context, kind string) (*indexjobs.Coverage, error)
	// List returns jobs matching the filter, newest first. A zero-value
	// SourceKind lists across every kind.
	List(ctx context.Context, filter indexjobs.ListFilter) ([]indexjobs.Job, error)
	// ActiveFailures returns the units with open (unresolved) failures,
	// one entry per unit, most-recently-failed first. An empty kind
	// lists across every kind, which the cross-kind triage panel relies
	// on.
	ActiveFailures(ctx context.Context, kind string, limit int) ([]indexjobs.FailedUnit, error)
	// Reindex enqueues manual-retry jobs for the kind (a single unit
	// when sourceID is set, every out-of-sync unit otherwise) and
	// returns the source ids enqueued. Returns indexjobs.ErrUnknownKind
	// for an unregistered kind.
	Reindex(ctx context.Context, kind, sourceID string) ([]string, error)
	// Resolve dismisses every open failure for the unit, the explicit
	// fallback when a failure will never be superseded. Returns the
	// number of failed rows resolved (zero is not an error).
	Resolve(ctx context.Context, kind, sourceID string) (int, error)
}

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

type NotificationHistory = notifyapi.HistoryStore

type OAuthKindHandler = connoauthapi.OAuthKindHandler

type OAuthKindHandlers = connoauthapi.OAuthKindHandlers

type PersonaRegistry interface {
	All() []*persona.Persona
	Get(name string) (*persona.Persona, bool)
	Register(p *persona.Persona) error
	Unregister(name string) error
}

type PlatformAuthOption func(*PlatformAuthenticator)

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

type PromptInfoProvider interface {
	AllPromptInfos() []registry.PromptInfo
}

type PromptRegistrar interface {
	RegisterRuntimePrompt(p *prompt.Prompt)
	UnregisterRuntimePrompt(name string)
}

type ReloadNotifier interface {
	PublishCatalogReload(catalogID string)
	PublishConnectionReload(kind, name string, op platform.ConnectionReloadOp)
	PublishPersonaReload()
	PublishAPIKeyReload()
}

type ToolActivityAggregate struct {
	WindowSeconds int64   `json:"window_seconds"`
	CallCount     int     `json:"call_count"`
	SuccessRate   float64 `json:"success_rate"`
	AvgDurationMs float64 `json:"avg_duration_ms"`
}

type ToolDetail struct {
	Name        string `json:"name"`
	Title       string `json:"title,omitempty"`
	Description string `json:"description"`

	ToolkitKind string `json:"toolkit_kind"`
	ToolkitName string `json:"toolkit_name,omitempty"`
	Connection  string `json:"connection,omitempty"`

	// JSON Schema for the tool's input parameters.
	InputSchema any `json:"input_schema,omitempty"`

	// Persona allow/deny matrix — one entry per database-managed
	// persona, with the matched pattern and source recorded.
	Personas []ToolPersonaAccess `json:"personas"`

	// HiddenByGlobalDeny is true when the platform-level tools.deny
	// list matches this tool. GlobalDenyPattern is the matching glob.
	HiddenByGlobalDeny bool   `json:"hidden_by_global_deny"`
	GlobalDenyPattern  string `json:"global_deny_pattern,omitempty"`

	// HiddenByPersona maps persona name → true for any persona where
	// this tool is denied.
	HiddenByPersona map[string]bool `json:"hidden_by_persona,omitempty"`

	// Description-override status (populated when a
	// tool.<name>.description config-entry exists).
	DescriptionOverridden bool   `json:"description_overridden"`
	OverrideAuthor        string `json:"override_author,omitempty"`

	Activity *ToolActivityAggregate `json:"activity,omitempty"`

	// Number of cross-enrichment rules attached to this tool. Only
	// meaningful for proxied tools (kind=mcp); zero for native.
	EnrichmentRuleCount int `json:"enrichment_rule_count"`
}

type ToolPersonaAccess struct {
	Persona           string               `json:"persona"`
	Allowed           bool                 `json:"allowed"`
	MatchedPattern    string               `json:"matched_pattern,omitempty"`
	Source            persona.AccessSource `json:"source"`
	ConnectionAllowed bool                 `json:"connection_allowed"`
}

type ToolkitRegistry interface {
	All() []registry.Toolkit
	AllTools() []string
	GetToolkitForTool(toolName string) registry.ToolkitMatch
}

type User struct {
	UserID string
	Email  string
	Roles  []string
	// FromCookie is true when the user authenticated via a browser session
	// cookie (as opposed to an API key / Bearer token). Cookie-authenticated
	// requests are the only ones subject to CSRF enforcement, since the
	// browser attaches the cookie automatically on cross-site requests.
	FromCookie bool
}