kes

type AuditHandler interface {
	// Enabled reports whether the handler handles records at
	// the given level. The handler ignores records whose level
	// is lower. It is called early, before an audit record is
	// created, to safe effort if the audit event should be
	// discarded.
	//
	// The Server will pass the request context as the first
	// argument, or context.Background() if no context is
	// available. Enabled may use the context to make a
	// decision.
	Enabled(context.Context, slog.Level) bool

	// Handle handles the AuditRecord. It will only be called when
	// Enabled returns true.
	//
	// The context is present for providing AuditHandlers access
	// to the context's values and to potentially pass it to an
	// underlying slog.Handler. Canceling the context should not
	// affect record processing.
	Handle(context.Context, AuditRecord) error
}

type AuditLogHandler struct {
	Handler slog.Handler
}

type AuditRecord struct {
	// Point in time when the audit event happened.
	Time time.Time

	// The request HTTP method. (GET, PUT, ...)
	Method string

	// Request URL path. Always starts with a '/'.
	Path string

	// Identity that send the request.
	Identity kes.Identity

	// IP address of the client that sent the request.
	RemoteIP netip.Addr

	// Status code the KES server responded with.
	StatusCode int

	// Amount of time the server took to process the
	// request and generate a response.
	ResponseTime time.Duration

	// The log level of this event.
	Level slog.Level

	// The log message describing the event.
	Message string
}

type CacheConfig struct {
	// Expiry controls how long a particular key resides
	// in the cache. If zero or negative, keys remain in
	// the cache as long as the KES server has sufficient
	// memory.
	Expiry time.Duration

	// ExpiryUnused is the interval in which a particular
	// key must be accessed to remain in the cache. Keys
	// that haven't been accessed get evicted from the
	// cache. The general cache expiry still applies.
	//
	// ExpiryUnused does nothing if <= 0 or greater than
	// Expiry.
	ExpiryUnused time.Duration

	// ExpiryOffline controls how long a particular key
	// resides in the cache once the key store becomes
	// unavailable. It overwrites Expiry and ExpiryUnused
	// if the key store is not available. Once the key
	// store is available again, Expiry and ExpiryUnused,
	// if set, apply.
	//
	// A common use of ExpiryOffline is reducing the impact
	// of a key store outage, and therefore, improving
	// availability.
	//
	// Offline caching is disabled if ExpiryOffline <= 0.
	ExpiryOffline time.Duration
}

type Config struct {
	// Admin is the KES server admin identity. It must not be empty.
	// To disable admin access set it to a non-hex value. For example,
	// "disabled".
	Admin kes.Identity

	// TLS contains the KES server's TLS configuration.
	//
	// A KES server requires a TLS certificate. Therefore, either
	// Config.Certificates, Config.GetCertificate or
	// Config.GetConfigForClient must be set.
	//
	// Further, the KES server has to request client certificates
	// for mTLS authentication. Hence, Config.ClientAuth must be
	// at least tls.RequestClientCert.
	TLS *tls.Config

	// Cache specifies how long the KES server caches keys from the
	// KeyStore. If nil, caching is disabled.
	Cache *CacheConfig

	// Policies is a set of policies and identities. Each identity
	// must be assigned to a policy only once.
	Policies map[string]Policy

	// Keys is the KeyStore the KES server fetches keys from.
	Keys KeyStore

	// Routes allows customization of the KES server API routes. It
	// contains a set of API route paths, for example "/v1/status",
	// and the corresponding route configuration.
	//
	// The KES server uses sane defaults for all its API routes.
	Routes map[string]RouteConfig

	// ErrorLog is an optional handler for handling the server's
	// error log events. If nil, defaults to a slog.TextHandler
	// writing to os.Stderr. The server's error log level is
	// controlled by Server.ErrLevel.
	ErrorLog slog.Handler

	// AuditLog is an optional handler for handling the server's
	// audit log events. If nil, defaults to a slog.TextHandler
	// writing to os.Stdout. The server's audit log level is
	// controlled by Server.AuditLevel.
	AuditLog AuditHandler
}

type Identity = kes.Identity

type KeyStore interface {
	// Closes the key store and releases associated resources,
	// like background go routines, if any.
	io.Closer

	// Status returns the current state of the KeyStore.
	Status(context.Context) (KeyStoreState, error)

	// Create creates a new entry with the given name if and only
	// if no such entry exists.
	// Otherwise, Create returns kes.ErrKeyExists.
	Create(ctx context.Context, name string, value []byte) error

	// Delete removes the entry. It may return either no error or
	// kes.ErrKeyNotFound if no such entry exists.
	Delete(ctx context.Context, name string) error

	// Get returns the value for the given name. It returns
	// kes.ErrKeyNotFound if no such entry exits.
	Get(ctx context.Context, name string) ([]byte, error)

	// List returns the first n key names, that start with the given
	// prefix, and the next prefix from which the listing should
	// continue.
	//
	// It returns all keys with the prefix if n < 0 and less than n
	// names if n is greater than the number of keys with the prefix.
	//
	// An empty prefix matches any key name. At the end of the listing
	// or when there are no (more) keys starting with the prefix, the
	// returned prefix is empty.
	List(ctx context.Context, prefix string, n int) ([]string, string, error)
}

type KeyStoreState struct {
	Latency time.Duration
}

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

type Policy struct {
	Allow map[string]kes.Rule // Set of allow rules

	Deny map[string]kes.Rule // Set of deny rules

	Identities []kes.Identity
}

type RouteConfig struct {
	// Timeout specifies when the API handler times out.
	//
	// A handler times out when it fails to send the
	// *entire* response body to the client within the
	// given time period.
	//
	// If <= 0, timeouts are disabled for the API route.
	//
	// Disabling timeouts may leave client/server connections
	// hung or allow certain types of denial-of-service (DOS)
	// attacks.
	Timeout time.Duration

	// InsecureSkipAuth, if set, disables authentication for the
	// API route. It allows anyone that can send HTTPS requests
	// to the KES server to invoke the API.
	//
	// For example the KES readiness API authentication may be
	// disabled when the probing clients do not support mTLS
	// client authentication
	//
	// If setting InsecureSkipAuth for any API then clients that
	// do not send a client certificate during the TLS handshake
	// no longer encounter a TLS handshake error but receive a
	// HTTP error instead. In particular, when the server's TLS
	// client auth type has been set  tls.RequireAnyClientCert
	// or tls.RequireAndVerifyClientCert.
	InsecureSkipAuth bool
}

type Server struct {
	// ShutdownTimeout controls how long Server.Close
	// tries to shutdown the server gracefully without
	// interrupting any active connections.
	//
	// If 0, defaults to ServerShutdownTimeout. If
	// negative, Server.Close waits indefinitely for
	// connections to return to idle and then shut down.
	ShutdownTimeout time.Duration

	// ErrLevel controls which errors are logged by the server.
	// It may be adjusted after the server has been started to
	// change its logging behavior.
	//
	// Log records are passed to the Config.ErrorLog handler
	// if and only if their log level is equal or greater than
	// ErrLevel. A custom Config.ErrorLog may handle records
	// independently from this ErrLevel.
	//
	// Defaults to slog.LevelInfo which includes TLS and HTTP
	// errors when handling requests.
	ErrLevel slog.LevelVar

	// AuditLevel controls which audit events are logged by
	// the server. It may be adjusted after the server has
	// been started to change its logging behavior.
	//
	// Log records are passed to the Config.AuditLog handler
	// if and only if their log level is equal or greater than
	// AuditLevel. A custom Config.AuditLog may handle records
	// independently from this AuditLevel.
	//
	// Defaults to slog.LevelInfo.
	AuditLevel slog.LevelVar
	// contains filtered or unexported fields
}