Documentation
¶
Overview ¶
Package auth provides role-based request authorization for the server.
It derives caller identity from the client certificate presented over mTLS and enforces access via a simple role allowlist. The recognized roles are:
- RoleControlPlane: control-plane callers (CLI and automation)
- RoleWorker: node agents pushing heartbeats/logs/diffs/artifacts
- RoleCLIAdmin: privileged CLI operations (e.g., PKI endpoints)
Identity is extracted from the client certificate Subject OU(s) or, as a fallback, the Subject CN. Common aliases are normalized (e.g., "admin", "cliadmin" → RoleCLIAdmin; "control", "controlplane" → RoleControlPlane).
When AllowInsecure is enabled in Options, the middleware permits plaintext requests and assigns DefaultRole. This is intended strictly for local tests and insecure development flows; production should require mTLS.
Index ¶
- Constants
- func ContextWithIdentity(ctx context.Context, identity Identity) context.Context
- func GenerateAPIToken(secret, role string, expiresAt time.Time) (string, error)
- func GenerateBootstrapToken(secret string, nodeID domaintypes.NodeID, expiresAt time.Time) (string, error)
- func WithQueryTokenAllowed(next http.Handler) http.Handler
- type Authorizer
- type Identity
- type Options
- type Role
- type TokenClaims
Constants ¶
const ( TokenTypeAPI = "api" // Long-lived API tokens for CLI TokenTypeBootstrap = "bootstrap" // Short-lived tokens for node bootstrapping )
Token types
Variables ¶
This section is empty.
Functions ¶
func ContextWithIdentity ¶
ContextWithIdentity returns a new context with the given identity attached. This is primarily intended for testing handlers that require caller identity.
func GenerateAPIToken ¶
GenerateAPIToken creates a long-lived bearer token for CLI usage.
func GenerateBootstrapToken ¶
func GenerateBootstrapToken(secret string, nodeID domaintypes.NodeID, expiresAt time.Time) (string, error)
GenerateBootstrapToken creates a short-lived token for node bootstrapping.
func WithQueryTokenAllowed ¶
WithQueryTokenAllowed wraps a handler to indicate that query-parameter token authentication is permitted on this route. The flag is read by identityFromRequest to decide whether to accept auth_token query params.
Types ¶
type Authorizer ¶
type Authorizer struct {
// contains filtered or unexported fields
}
Authorizer enforces role-based access derived from client certificates. Use Middleware to wrap HTTP handlers with the required role allowlist.
func NewAuthorizer ¶
func NewAuthorizer(opts Options) *Authorizer
NewAuthorizer constructs an Authorizer.
func (*Authorizer) Middleware ¶
Middleware enforces the provided role allowlist (empty slice permits any role while still requiring TLS).
func (*Authorizer) Wait ¶
func (a *Authorizer) Wait()
Wait blocks until all in-flight background work (e.g. token last-used updates) completes. Call during server shutdown for graceful drain.
type Options ¶
type Options struct {
AllowInsecure bool
DefaultRole Role
TokenSecret string // JWT signing secret for bearer token validation
Querier store.Querier // Database querier for token validation
Logger *slog.Logger // Structured logger for auth events
}
Options configure the Authorizer.
When AllowInsecure is true, requests without TLS are allowed and DefaultRole is assigned as the caller's role. In secure deployments, set AllowInsecure to false so that mutual TLS is mandatory.
type Role ¶
type Role string
Role represents an authentication role for access control.
const ( RoleControlPlane Role = "control-plane" RoleWorker Role = "worker" RoleCLIAdmin Role = "cli-admin" )
Role constants encode connection-level privileges.
func NormalizeRole ¶
NormalizeRole normalizes a role string to one of the standard role constants. It accepts common aliases and returns the canonical role name. Returns empty Role if the value doesn't match any known role.
Aliases exist because certificate OUs and CNs may use different naming conventions depending on when they were issued:
control-plane: "beacon" (legacy agent name), "control", "controlplane",
"client" (generic TLS client)
worker: "node" (cert CN prefix for node agents)
cli-admin: "cliadmin", "admin"
type TokenClaims ¶
type TokenClaims struct {
Role string `json:"role"` // "cli-admin", "control-plane", "worker"
TokenType string `json:"token_type"` // "api" or "bootstrap"
NodeID domaintypes.NodeID `json:"node_id,omitempty"` // Only for bootstrap tokens
jwt.RegisteredClaims
}
TokenClaims is the JWT claims structure used by API and bootstrap bearer tokens.
func ValidateToken ¶
func ValidateToken(tokenString, secret string) (*TokenClaims, error)
ValidateToken verifies and parses a JWT token
Source Files