api

Documentation

Index

• Constants
• Variables
• func ActorName(ctx context.Context) string
• func ActorOf(ctx context.Context) *models.Operator
• func IsHostIPValidationError(err error) bool
• type HostSeenEmitter
• type Server
  • func NewServer(s store.Store, logger *slog.Logger) *Server
  • func (s *Server) RecordLogin(result, factor string)
  • func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (s *Server) WithCAResolver(r *pki.CAResolver)
  • func (s *Server) WithDefaultCAID(id string)
  • func (s *Server) WithEnrollmentTokenTTL(ttl time.Duration)
  • func (s *Server) WithHostSeenEmitter(emit HostSeenEmitter)
  • func (s *Server) WithMaster(m *keystore.Master)
  • func (s *Server) WithMetricsEnabled(enabled bool)
  • func (s *Server) WithPasswordPolicy(p auth.Policy)
  • func (s *Server) WithRateLimiter(l *ratelimit.Limiter)

Constants

const (
	ResultOK     = "ok"
	ResultDenied = "denied"
	ResultError  = "error"
)

Result labels for counters whose terminal outcome falls into one of three buckets (request succeeded / was refused / failed unexpectedly). Used by enrollments, cert renewals, and operator logins. Exported so the Web UI package can use the same constants when reporting login outcomes back to the API server via RecordLogin.

const (
	LoginFactorPassword = "password"
	LoginFactorTOTP     = "totp"
	LoginFactorRecovery = "recovery"
	LoginFactorOIDC     = "oidc"
)

Authentication factor labels for nebula_mgmt_operator_logins_total.

const SigningPublicKeyPEMType = "NEBULA ED25519 PUBLIC KEY"

SigningPublicKeyPEMType is the PEM block type used by the agent for its Ed25519 poll-signature public key (ADR 0004 §7.1). Distinct from the X25519 `NEBULA X25519 PRIVATE KEY` / `NEBULA X25519 PUBLIC KEY` banners that slackhq/nebula/cert owns.

Variables

var ErrBadSigningPEM = errors.New("bad signing public key PEM")

ErrBadSigningPEM is returned when an Ed25519 signing public key PEM is missing, the wrong block type, or the wrong byte length.

Functions

func ActorName

func ActorName(ctx context.Context) string

ActorName returns a stable string identifier for the actor, suitable for audit log entries. Returns "unknown" if no actor is on the context — this should not happen on routes guarded by bearerAuth.

func ActorOf

func ActorOf(ctx context.Context) *models.Operator

ActorOf returns the operator attached to the request context. On protected API routes bearerAuth guarantees a non-nil value; nil indicates an unauthenticated context (e.g. public endpoints, tests).

func IsHostIPValidationError

func IsHostIPValidationError(err error) bool

IsHostIPValidationError reports whether err is a user-facing validation failure rather than an internal error.

Types

type HostSeenEmitter

type HostSeenEmitter func(hostID string, lastSeen time.Time, networkID string)

HostSeenEmitter is invoked after every successful agent poll so the Web UI can stream a live "host X just polled" event over its SSE endpoint. hostID is the DB id, lastSeen is the wall-clock timestamp the agent's poll was observed at, and networkID is included so per-network views can filter without an extra lookup.

type Server

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

Server is the HTTP API server.

func NewServer

func NewServer(s store.Store, logger *slog.Logger) *Server

NewServer creates a new API server.

func (*Server) RecordLogin

func (s *Server) RecordLogin(result, factor string)

RecordLogin records an operator login attempt against the server's Prometheus metrics. Exposed so the Web UI handlers (a separate package) can plumb their login outcomes through without an import cycle.

Result is one of "ok" / "denied" / "error"; factor is one of "password" / "totp" / "recovery" / "oidc".

func (*Server) ServeHTTP

func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements http.Handler.

func (*Server) WithCAResolver

func (s *Server) WithCAResolver(r *pki.CAResolver)

WithCAResolver attaches a CAResolver. Must be called before ServeHTTP. When set, host signing operations look up the CA by host.CAID; the legacy single-CA fallback is used only when host.CAID is empty.

func (*Server) WithDefaultCAID

func (s *Server) WithDefaultCAID(id string)

WithDefaultCAID records the id of the CA seeded from the legacy on-disk material. Used when host.CAID matches this id to short-circuit to the legacy in-memory CAManager.

func (*Server) WithEnrollmentTokenTTL

func (s *Server) WithEnrollmentTokenTTL(ttl time.Duration)

WithEnrollmentTokenTTL sets the default enrollment-token TTL applied when the per-network override is unset. Default is 24h (ADR 0004 §7.1).

func (*Server) WithHostSeenEmitter

func (s *Server) WithHostSeenEmitter(emit HostSeenEmitter)

WithHostSeenEmitter wires the callback the API server fires when an agent polls. Passing nil disables emission.

func (*Server) WithMaster

func (s *Server) WithMaster(m *keystore.Master)

WithMaster sets the master keystore used to create new CAs.

func (*Server) WithMetricsEnabled

func (s *Server) WithMetricsEnabled(enabled bool)

WithMetricsEnabled toggles the Prometheus /metrics endpoint. Disable in air-gapped deployments where the exporter is not scraped. Must be called before the router is exercised by ServeHTTP — re-wires the routes.

func (*Server) WithPasswordPolicy

func (s *Server) WithPasswordPolicy(p auth.Policy)

WithPasswordPolicy installs the policy applied to every server-side password-setting path (operator create, future operator reset).

func (*Server) WithRateLimiter

func (s *Server) WithRateLimiter(l *ratelimit.Limiter)

WithRateLimiter installs a rate-limit middleware. nil disables limiting.