admin

Documentation

Overview

Package admin provides the admin API HTTP server. It runs on a separate port from the public OAuth server.

Index

• type AuditRecorder
• type AuthWrapper
• type BrokerProviderAdminDeps
• type DCRAdmin
• type DCRDeps
• type ExtraRoute
• type FrontingAdminDeps
• type GrantAdminDeps
• type IssuanceAdminDeps
• type KeyAdmin
• type KeysDeps
• type OptionalDeps
• type Provider
• type ResourceAdminDeps
• type Server
  • func NewServer(ctx context.Context, cfg config.AdminConfig, admin Provider, ...) (*Server, error)
  • func (s *Server) Handler() http.Handler
  • func (s *Server) Shutdown(ctx context.Context) error
  • func (s *Server) Start() error
• type SettingsStore
• type SystemDeps
• type XAADeps

Types

type AuditRecorder

type AuditRecorder interface {
	Record(ctx context.Context, e audit.Event)
}

AuditRecorder records audit events. Matches services.AuditRecorder.

type AuthWrapper

type AuthWrapper interface {
	Wrap(http.Handler) http.Handler
}

AuthWrapper wraps an HTTP handler with an auth gate. *apiKeyMiddleware satisfies it; an alternative strategy can be injected via OptionalDeps.Auth.

type BrokerProviderAdminDeps

type BrokerProviderAdminDeps struct {
	BrokerProviders input.BrokerProviderAdminPort
}

BrokerProviderAdminDeps holds optional broker-provider admin dependencies.

type DCRAdmin

type DCRAdmin interface {
	GetMode(ctx context.Context) (string, error)
	SetMode(ctx context.Context, mode string) error
}

DCRAdmin is the local interface for reading/setting DCR mode at runtime.

type DCRDeps

type DCRDeps struct {
	DCR      DCRAdmin
	Settings SettingsStore
	Audit    AuditRecorder
}

DCRDeps holds DCR settings management dependencies for the admin server.

type ExtraRoute

type ExtraRoute struct {
	Pattern string // ServeMux pattern; its path must route under /admin/
	Handler http.Handler
}

ExtraRoute is one downstream-supplied admin route. Feature-agnostic: the server knows nothing about what the handler does. Registered on the same mux and behind the same auth wrapper as every built-in admin route.

type FrontingAdminDeps

type FrontingAdminDeps struct {
	Fronting input.FrontingAdminPort
}

FrontingAdminDeps holds optional fronting-admin dependencies.

type GrantAdminDeps

type GrantAdminDeps struct {
	Grants input.GrantAdminPort
}

GrantAdminDeps holds optional grant-admin dependencies.

type IssuanceAdminDeps

type IssuanceAdminDeps struct {
	Issuances input.IssuanceAdminPort
}

IssuanceAdminDeps holds optional issuance-admin dependencies.

type KeyAdmin

type KeyAdmin interface {
	BuildJWKS(ctx context.Context) (*jose.JSONWebKeySet, error)
	RotateKey(ctx context.Context) (*output.SigningKey, error)
}

KeyAdmin is the local interface for key administration. The JWKSService implements both methods.

type KeysDeps

type KeysDeps struct {
	KeyAdmin KeyAdmin
	Audit    AuditRecorder
}

KeysDeps holds optional key management dependencies for the admin server.

type OptionalDeps

type OptionalDeps struct {
	System          *SystemDeps
	Keys            *KeysDeps
	DCR             *DCRDeps
	XAA             *XAADeps
	Resources       *ResourceAdminDeps
	BrokerProviders *BrokerProviderAdminDeps
	Grants          *GrantAdminDeps
	Issuances       *IssuanceAdminDeps
	Fronting        *FrontingAdminDeps
	Auth            AuthWrapper  // optional external auth strategy; when set, replaces the API-key gate. Must be non-nil if set (a typed-nil defeats the presence check and panics at construction).
	ExtraRoutes     []ExtraRoute // optional downstream-supplied admin routes, registered behind the same auth gate and middleware chain as built-in routes; nil in the default binary
}

OptionalDeps groups optional admin server dependencies. All fields are nil-safe — omit any that are not configured.

type Provider

type Provider interface {
	input.AdminPort
}

Provider is the local interface mirroring input.AdminPort.

type ResourceAdminDeps

type ResourceAdminDeps struct {
	Resources input.ResourceAdminPort
}

ResourceAdminDeps holds optional unified-resource admin dependencies.

type Server

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

Server is the admin API HTTP server.

func NewServer

func NewServer(ctx context.Context, cfg config.AdminConfig, admin Provider, obs *observability.Provider, opts OptionalDeps) (*Server, error)

NewServer creates the admin HTTP server with routes wired. opts fields are all optional (nil if not configured). It returns an error when a downstream-supplied extra route is malformed (see registerRoutes); the default binary supplies none and never sees a non-nil error.

func (*Server) Handler

func (s *Server) Handler() http.Handler

Handler returns the server's HTTP handler for testing.

func (*Server) Shutdown

func (s *Server) Shutdown(ctx context.Context) error

Shutdown gracefully drains in-flight requests.

func (*Server) Start

func (s *Server) Start() error

Start begins listening.

type SettingsStore

type SettingsStore interface {
	Get(ctx context.Context, key string) (string, error)
	Set(ctx context.Context, key, value string) error
}

SettingsStore is the local interface for persisting runtime settings.

type SystemDeps

type SystemDeps struct {
	// Process-global — static (no per-request provider).
	Version          string
	StartTime        time.Time
	DBPing           func(ctx context.Context) error
	StorageDriver    string
	KeyStoreDriver   string
	EncryptionDriver string
	SigningAlgorithm string
	RateLimitEnabled bool
	Audit            AuditRecorder

	// Per-request — resolved with r.Context() via the provider ports.
	Issuer            output.IssuerProvider
	DPoP              output.DPoPConfigProvider
	DCRMode           output.DCRModeProvider
	TokenExchange     output.TokenExchangeConfigProvider
	ClientCredentials output.ClientCredentialsConfigProvider
	Agents            output.AgentsConfigProvider
	// OIDC is a secret-bearing port (its OIDCConfig carries ClientSecret);
	// read only .Enabled here.
	OIDC output.OIDCConfigProvider
}

SystemDeps holds optional system dependencies for admin system endpoints. The values these handlers write to the response are sanitized — no secrets, DSNs, or private key material reach the wire. Caveat: the OIDC field is a full OIDCConfigProvider whose OIDCConfig carries the upstream client secret; the only sanctioned read here is oidc.Enabled. Do not serialize more of that config from these handlers without re-checking for secret leakage.

type XAADeps

type XAADeps struct {
	IDP            input.XAAIDPPort
	Policy         input.XAAPolicyPort
	SubjectMapping input.SubjectMappingPort
	Config         output.XAAConfigProvider // per-request feature gate
}

XAADeps holds optional XAA dependencies for the admin server.